[Python-checkins] cpython: asyncio doc: add a "Coroutines and protocols" section

Fri Jan 24 17:33:29 CET 2014

http://hg.python.org/cpython/rev/3e7eddf7b328
changeset: 88670:3e7eddf7b328
user: Victor Stinner <victor.stinner at gmail.com>
date: Fri Jan 24 17:33:20 2014 +0100
summary:
 asyncio doc: add a "Coroutines and protocols" section
files:
 Doc/library/asyncio-protocol.rst | 12 ++++++++++++
 Doc/library/asyncio-stream.rst | 2 ++
 2 files changed, 14 insertions(+), 0 deletions(-)

diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -403,6 +403,18 @@
 mark is zero.
 
 
+Coroutines and protocols
+------------------------
+
+Coroutines can be scheduled in a protocol method using :func:`async`, but there
+is not guarantee on the execution order. Protocols are not aware of coroutines
+created in protocol methods and so will not wait for them.
+
+To have a reliable execution order, use :ref:`stream objects <streams>` in a
+coroutine with ``yield from``. For example, the :meth:`StreamWriter.drain`
+coroutine can be used to wait until the write buffer is flushed.
+
+
 Server
 ------
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -1,5 +1,7 @@
 .. currentmodule:: asyncio
 
+.. _streams:
+
 ++++++++++++++++++++++++
 Streams (high-level API)
 ++++++++++++++++++++++++
-- 
Repository URL: http://hg.python.org/cpython
