From: Ben Darnell <ben@bendarnell.com>
Date: Sun, 15 Feb 2015 16:40:46 +0000 (-0500)
Subject: Document the limitations of read_until_close(streaming_callback=).
X-Git-Tag: v4.2.0b1~115
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3e311aaf2ea85940e2fa7b14f63ed96c13d40be2;p=thirdparty%2Ftornado.git

Document the limitations of read_until_close(streaming_callback=).

As noted in #1334 and #1339.
---

diff --git a/tornado/iostream.py b/tornado/iostream.py
index 6d039a4ad..08701a0c5 100644
--- a/tornado/iostream.py
+++ b/tornado/iostream.py
@@ -319,9 +319,16 @@ class BaseIOStream(object):
         If a callback is given, it will be run with the data as an argument;
         if not, this method returns a `.Future`.
 
+        Note that if a ``streaming_callback`` is used, data will be
+        read from the socket as quickly as it becomes available; there
+        is no way to apply backpressure or cancel the reads. If flow
+        control or cancellation are desired, use a loop with
+        `read_bytes(partial=True) <.read_bytes>` instead.
+
         .. versionchanged:: 4.0
             The callback argument is now optional and a `.Future` will
             be returned if it is omitted.
+
         """
         future = self._set_read_callback(callback)
         self._streaming_callback = stack_context.wrap(streaming_callback)