From: Victor Stinner Date: Fri, 28 Nov 2014 16:45:41 +0000 (+0100) Subject: Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation X-Git-Tag: v3.4.3rc1~292 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e7182979d6e8178e4bbcc50beb142624b1a88223;p=thirdparty%2FPython%2Fcpython.git Closes #22348: Rephrase asyncio.StreamWriter.drain() documentation Patch written by Martin Richard. --- diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 348132a5b7b6..3809d947d5cc 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -170,16 +170,22 @@ StreamWriter .. method:: drain() - Wait until the write buffer of the underlying transport is flushed. + Let the write buffer of the underlying transport a chance to be flushed. The intended use is to write:: w.write(data) yield from w.drain() - When the transport buffer is full (the protocol is paused), block until - the buffer is (partially) drained and the protocol is resumed. When there - is nothing to wait for, the yield-from continues immediately. + When the size of the transport buffer reaches the high-water limit (the + protocol is paused), block until the size of the buffer is drained down + to the low-water limit and the protocol is resumed. When there is nothing + to wait for, the yield-from continues immediately. + + Yielding from :meth:`drain` gives the opportunity for the loop to + schedule the write operation and flush the buffer. It should especially + be used when a possibly large amount of data is written to the transport, + and the coroutine does not yield-from between calls to :meth:`write`. This method is a :ref:`coroutine `. diff --git a/Misc/ACKS b/Misc/ACKS index 30b6a0ec22d9..d4ec65929389 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1125,6 +1125,7 @@ Francesco Ricciardi Tim Rice Jan Pieter Riegel Armin Rigo +Martin Richard Arc Riley Nicholas Riley Jean-Claude Rimbault