asyncio doc: reorder sections

1 files changed, 428 insertions, 428 deletions

diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index 7ee2142..61ee38b 100644
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -326,28 +326,6 @@ Creating connections
      to bind the socket to locally.  The *local_host* and *local_port*
      are looked up using getaddrinfo(), similarly to *host* and *port*.
 
-.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
-
-   Register read pipe in eventloop.
-
-   *protocol_factory* should instantiate object with :class:`Protocol`
-   interface.  pipe is file-like object already switched to nonblocking.
-   Return pair (transport, protocol), where transport support
-   :class:`ReadTransport` interface.
-
-   This method returns a :ref:`coroutine <coroutine>`.
-
-.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
-
-   Register write pipe in eventloop.
-
-   *protocol_factory* should instantiate object with :class:`BaseProtocol`
-   interface.  Pipe is file-like object already switched to nonblocking.
-   Return pair (transport, protocol), where transport support
-   :class:`WriteTransport` interface.
-
-   This method returns a :ref:`coroutine <coroutine>`.
-
 
 Resolve name
 ^^^^^^^^^^^^
@@ -382,235 +360,255 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
 
    See the constructor of the :class:`subprocess.Popen` class for parameters.
 
+.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
 
-Network functions
------------------
+   Register read pipe in eventloop.
 
-.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+   *protocol_factory* should instantiate object with :class:`Protocol`
+   interface.  pipe is file-like object already switched to nonblocking.
+   Return pair (transport, protocol), where transport support
+   :class:`ReadTransport` interface.
 
-   A wrapper for create_connection() returning a (reader, writer) pair.
+   This method returns a :ref:`coroutine <coroutine>`.
 
-   The reader returned is a StreamReader instance; the writer is a
-   :class:`Transport`.
+.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
 
-   The arguments are all the usual arguments to
-   :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.
+   Register write pipe in eventloop.
 
-   Additional optional keyword arguments are *loop* (to set the event loop
-   instance to use) and *limit* (to set the buffer limit passed to the
-   StreamReader).
+   *protocol_factory* should instantiate object with :class:`BaseProtocol`
+   interface.  Pipe is file-like object already switched to nonblocking.
+   Return pair (transport, protocol), where transport support
+   :class:`WriteTransport` interface.
 
-   (If you want to customize the :class:`StreamReader` and/or
-   :class:`StreamReaderProtocol` classes, just copy the code -- there's really
-   nothing special here except some convenience.)
+   This method returns a :ref:`coroutine <coroutine>`.
 
-   This function returns a :ref:`coroutine <coroutine>`.
 
-.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+.. _coroutine:
 
-   Start a socket server, call back for each client connected.
+Coroutines
+----------
 
-   The first parameter, *client_connected_cb*, takes two parameters:
-   *client_reader*, *client_writer*.  *client_reader* is a
-   :class:`StreamReader` object, while *client_writer* is a
-   :class:`StreamWriter` object.  This parameter can either be a plain callback
-   function or a :ref:`coroutine <coroutine>`; if it is a coroutine, it will be
-   automatically converted into a :class:`Task`.
+A coroutine is a generator that follows certain conventions.  For
+documentation purposes, all coroutines should be decorated with
+``@asyncio.coroutine``, but this cannot be strictly enforced.
 
-   The rest of the arguments are all the usual arguments to
-   :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.  The return value is the same as
-   :meth:`~BaseEventLoop.create_server()`.
+Coroutines use the ``yield from`` syntax introduced in :pep:`380`,
+instead of the original ``yield`` syntax.
 
-   Additional optional keyword arguments are *loop* (to set the event loop
-   instance to use) and *limit* (to set the buffer limit passed to the
-   :class:`StreamReader`).
+The word "coroutine", like the word "generator", is used for two
+different (though related) concepts:
 
-   The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
-   a :class:`AbstractServer` object which can be used to stop the service.
+- The function that defines a coroutine (a function definition
+  decorated with ``asyncio.coroutine``).  If disambiguation is needed
+  we will call this a *coroutine function*.
 
-   This function returns a :ref:`coroutine <coroutine>`.
+- The object obtained by calling a coroutine function.  This object
+  represents a computation or an I/O operation (usually a combination)
+  that will complete eventually.  If disambiguation is needed we will
+  call it a *coroutine object*.
 
+Things a coroutine can do:
 
-.. _protocol:
+- ``result = yield from future`` -- suspends the coroutine until the
+  future is done, then returns the future's result, or raises an
+  exception, which will be propagated.  (If the future is cancelled,
+  it will raise a ``CancelledError`` exception.)  Note that tasks are
+  futures, and everything said about futures also applies to tasks.
 
-Protocols
----------
+- ``result = yield from coroutine`` -- wait for another coroutine to
+  produce a result (or raise an exception, which will be propagated).
+  The ``coroutine`` expression must be a *call* to another coroutine.
 
-:mod:`asyncio` provides base classes that you can subclass to implement
-your network protocols.  Those classes are used in conjunction with
-:ref:`transports <transport>` (see below): the protocol parses incoming
-data and asks for the writing of outgoing data, while the transport is
-responsible for the actual I/O and buffering.
+- ``return expression`` -- produce a result to the coroutine that is
+  waiting for this one using ``yield from``.
 
-When subclassing a protocol class, it is recommended you override certain
-methods.  Those methods are callbacks: they will be called by the transport
-on certain events (for example when some data is received); you shouldn't
-call them yourself, unless you are implementing a transport.
+- ``raise exception`` -- raise an exception in the coroutine that is
+  waiting for this one using ``yield from``.
 
-.. note::
-   All callbacks have default implementations, which are empty.  Therefore,
-   you only need to implement the callbacks for the events in which you
-   are interested.
+Calling a coroutine does not start its code running -- it is just a
+generator, and the coroutine object returned by the call is really a
+generator object, which doesn't do anything until you iterate over it.
+In the case of a coroutine object, there are two basic ways to start
+it running: call ``yield from coroutine`` from another coroutine
+(assuming the other coroutine is already running!), or convert it to a
+:class:`Task`.
 
+Coroutines (and tasks) can only run when the event loop is running.
 
-Protocol classes
-^^^^^^^^^^^^^^^^
 
-.. class:: Protocol
+Task
+----
 
-   The base class for implementing streaming protocols (for use with
-   e.g. TCP and SSL transports).
+.. class:: Task(coro, \*, loop=None)
 
-.. class:: DatagramProtocol
+   A coroutine wrapped in a :class:`~concurrent.futures.Future`.
 
-   The base class for implementing datagram protocols (for use with
-   e.g. UDP transports).
+   .. classmethod:: all_tasks(loop=None)
 
-.. class:: SubprocessProtocol
+      Return a set of all tasks for an event loop.
 
-   The base class for implementing protocols communicating with child
-   processes (through a set of unidirectional pipes).
+      By default all tasks for the current event loop are returned.
 
+   .. method:: cancel()
 
-Connection callbacks
-^^^^^^^^^^^^^^^^^^^^
+      Cancel the task.
 
-These callbacks may be called on :class:`Protocol` and
-:class:`SubprocessProtocol` instances:
+   .. method:: get_stack(self, \*, limit=None)
 
-.. method:: BaseProtocol.connection_made(transport)
+      Return the list of stack frames for this task's coroutine.
 
-   Called when a connection is made.
+      If the coroutine is active, this returns the stack where it is suspended.
+      If the coroutine has completed successfully or was cancelled, this
+      returns an empty list.  If the coroutine was terminated by an exception,
+      this returns the list of traceback frames.
 
-   The *transport* argument is the transport representing the
-   connection.  You are responsible for storing it somewhere
-   (e.g. as an attribute) if you need to.
+      The frames are always ordered from oldest to newest.
 
-.. method:: BaseProtocol.connection_lost(exc)
+      The optional limit gives the maximum nummber of frames to return; by
+      default all available frames are returned.  Its meaning differs depending
+      on whether a stack or a traceback is returned: the newest frames of a
+      stack are returned, but the oldest frames of a traceback are returned.
+      (This matches the behavior of the traceback module.)
 
-   Called when the connection is lost or closed.
+      For reasons beyond our control, only one stack frame is returned for a
+      suspended coroutine.
 
-   The argument is either an exception object or :const:`None`.
-   The latter means a regular EOF is received, or the connection was
-   aborted or closed by this side of the connection.
+   .. method:: print_stack(\*, limit=None, file=None)
 
-:meth:`connection_made` and :meth:`connection_lost` are called exactly once
-per successful connection.  All other callbacks will be called between those
-two methods, which allows for easier resource management in your protocol
-implementation.
+      Print the stack or traceback for this task's coroutine.
 
-The following callbacks may be called only on :class:`SubprocessProtocol`
-instances:
+      This produces output similar to that of the traceback module, for the
+      frames retrieved by get_stack().  The limit argument is passed to
+      get_stack().  The file argument is an I/O stream to which the output
+      goes; by default it goes to sys.stderr.
 
-.. method:: SubprocessProtocol.pipe_data_received(fd, data)
 
-   Called when the child process writes data into its stdout or stderr pipe.
-   *fd* is the integer file descriptor of the pipe.  *data* is a non-empty
-   bytes object containing the data.
+Task functions
+--------------
 
-.. method:: SubprocessProtocol.pipe_connection_lost(fd, exc)
+.. function:: as_completed(fs, *, loop=None, timeout=None)
 
-   Called when one of the pipes communicating with the child process
-   is closed.  *fd* is the integer file descriptor that was closed.
+   Return an iterator whose values, when waited for, are
+   :class:`~concurrent.futures.Future` instances.
 
-.. method:: SubprocessProtocol.process_exited()
+   Raises :exc:`TimeoutError` if the timeout occurs before all Futures are done.
 
-   Called when the child process has exited.
+   Example::
 
+       for f in as_completed(fs):
+           result = yield from f  # The 'yield from' may raise
+           # Use result
 
-Data reception callbacks
-^^^^^^^^^^^^^^^^^^^^^^^^
+   .. note::
 
-Streaming protocols
-"""""""""""""""""""
+      The futures ``f`` are not necessarily members of fs.
 
-The following callbacks are called on :class:`Protocol` instances:
+.. function:: async(coro_or_future, *, loop=None)
 
-.. method:: Protocol.data_received(data)
+   Wrap a :ref:`coroutine <coroutine>` in a future.
 
-   Called when some data is received.  *data* is a non-empty bytes object
-   containing the incoming data.
+   If the argument is a :class:`~concurrent.futures.Future`, it is returned
+   directly.
 
-   .. note::
-      Whether the data is buffered, chunked or reassembled depends on
-      the transport.  In general, you shouldn't rely on specific semantics
-      and instead make your parsing generic and flexible enough.  However,
-      data is always received in the correct order.
+.. function:: gather(*coros_or_futures, loop=None, return_exceptions=False)
 
-.. method:: Protocol.eof_received()
+   Return a future aggregating results from the given coroutines or futures.
 
-   Calls when the other end signals it won't send any more data
-   (for example by calling :meth:`write_eof`, if the other end also uses
-   asyncio).
+   All futures must share the same event loop.  If all the tasks are done
+   successfully, the returned future's result is the list of results (in the
+   order of the original sequence, not necessarily the order of results
+   arrival).  If *result_exception* is True, exceptions in the tasks are
+   treated the same as successful results, and gathered in the result list;
+   otherwise, the first raised exception will be immediately propagated to the
+   returned future.
 
-   This method may return a false value (including None), in which case
-   the transport will close itself.  Conversely, if this method returns a
-   true value, closing the transport is up to the protocol.  Since the
-   default implementation returns None, it implicitly closes the connection.
+   Cancellation: if the outer Future is cancelled, all children (that have not
+   completed yet) are also cancelled.  If any child is cancelled, this is
+   treated as if it raised :exc:`~concurrent.futures.CancelledError` -- the
+   outer Future is *not* cancelled in this case.  (This is to prevent the
+   cancellation of one child to cause other children to be cancelled.)
 
-   .. note::
-      Some transports such as SSL don't support half-closed connections,
-      in which case returning true from this method will not prevent closing
-      the connection.
+.. function:: tasks.iscoroutinefunction(func)
 
-:meth:`data_received` can be called an arbitrary number of times during
-a connection.  However, :meth:`eof_received` is called at most once
-and, if called, :meth:`data_received` won't be called after it.
+   Return ``True`` if *func* is a decorated coroutine function.
 
-Datagram protocols
-""""""""""""""""""
+.. function:: tasks.iscoroutine(obj)
 
-The following callbacks are called on :class:`DatagramProtocol` instances.
+   Return ``True`` if *obj* is a coroutine object.
 
-.. method:: DatagramProtocol.datagram_received(data, addr)
+.. function:: sleep(delay, result=None, \*, loop=None)
 
-   Called when a datagram is received.  *data* is a bytes object containing
-   the incoming data.  *addr* is the address of the peer sending the data;
-   the exact format depends on the transport.
+   Create a :ref:`coroutine <coroutine>` that completes after a given time
+   (in seconds).
 
-.. method:: DatagramProtocol.error_received(exc)
+.. function:: shield(arg, \*, loop=None)
 
-   Called when a previous send or receive operation raises an
-   :class:`OSError`.  *exc* is the :class:`OSError` instance.
+   Wait for a future, shielding it from cancellation.
 
-   This method is called in rare conditions, when the transport (e.g. UDP)
-   detects that a datagram couldn't be delivered to its recipient.
-   In many conditions though, undeliverable datagrams will be silently
-   dropped.
+   The statement::
 
+       res = yield from shield(something())
 
-Flow control callbacks
-^^^^^^^^^^^^^^^^^^^^^^
+   is exactly equivalent to the statement::
 
-These callbacks may be called on :class:`Protocol` and
-:class:`SubprocessProtocol` instances:
+       res = yield from something()
 
-.. method:: BaseProtocol.pause_writing()
+   *except* that if the coroutine containing it is cancelled, the task running
+   in ``something()`` is not cancelled.  From the point of view of
+   ``something()``, the cancellation did not happen.  But its caller is still
+   cancelled, so the yield-from expression still raises
+   :exc:`~concurrent.futures.CancelledError`.  Note: If ``something()`` is
+   cancelled by other means this will still cancel ``shield()``.
 
-   Called when the transport's buffer goes over the high-water mark.
+   If you want to completely ignore cancellation (not recommended) you can
+   combine ``shield()`` with a try/except clause, as follows::
 
-.. method:: BaseProtocol.resume_writing()
+       try:
+           res = yield from shield(something())
+       except CancelledError:
+           res = None
 
-   Called when the transport's buffer drains below the low-water mark.
+.. function:: wait(fs, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
 
+   Wait for the Futures and coroutines given by fs to complete. Coroutines will
+   be wrapped in Tasks.  Returns two sets of
+   :class:`~concurrent.futures.Future`: (done, pending).
 
-:meth:`pause_writing` and :meth:`resume_writing` calls are paired --
-:meth:`pause_writing` is called once when the buffer goes strictly over
-the high-water mark (even if subsequent writes increases the buffer size
-even more), and eventually :meth:`resume_writing` is called once when the
-buffer size reaches the low-water mark.
+   *timeout* can be used to control the maximum number of seconds to wait before
+   returning.  *timeout* can be an int or float.  If *timeout* is not specified
+   or ``None``, there is no limit to the wait time.
 
-.. note::
-   If the buffer size equals the high-water mark,
-   :meth:`pause_writing` is not called -- it must go strictly over.
-   Conversely, :meth:`resume_writing` is called when the buffer size is
-   equal or lower than the low-water mark.  These end conditions
-   are important to ensure that things go as expected when either
-   mark is zero.
+   *return_when* indicates when this function should return.  It must be one of
+   the following constants of the :mod`concurrent.futures` module:
+
+   .. tabularcolumns:: |l|L|
+
+   +-----------------------------+----------------------------------------+
+   | Constant                    | Description                            |
+   +=============================+========================================+
+   | :const:`FIRST_COMPLETED`    | The function will return when any      |
+   |                             | future finishes or is cancelled.       |
+   +-----------------------------+----------------------------------------+
+   | :const:`FIRST_EXCEPTION`    | The function will return when any      |
+   |                             | future finishes by raising an          |
+   |                             | exception.  If no future raises an     |
+   |                             | exception then it is equivalent to     |
+   |                             | :const:`ALL_COMPLETED`.                |
+   +-----------------------------+----------------------------------------+
+   | :const:`ALL_COMPLETED`      | The function will return when all      |
+   |                             | futures finish or are cancelled.       |
+   +-----------------------------+----------------------------------------+
+
+   This function returns a :ref:`coroutine <coroutine>`.
+
+   Usage::
+
+        done, pending = yield from asyncio.wait(fs)
+
+   .. note::
+
+      This does not raise :exc:`TimeoutError`! Futures that aren't done when
+      the timeout occurs are returned in the second set.
 
 
 .. _transport:
@@ -714,38 +712,21 @@ Methods of writable streaming transports: WriteTransport
 
    Interface for write-only transports.
 
-   .. method:: write(data)
-
-      Write some *data* bytes to the transport.
-
-      This method does not block; it buffers the data and arranges for it
-      to be sent out asynchronously.
-
-   .. method:: writelines(list_of_data)
-
-      Write a list (or any iterable) of data bytes to the transport.
-      This is functionally equivalent to calling :meth:`write` on each
-      element yielded by the iterable, but may be implemented more efficiently.
-
-   .. method:: write_eof()
-
-      Close the write end of the transport after flushing buffered data.
-      Data may still be received.
+   .. method:: abort()
 
-      This method can raise :exc:`NotImplementedError` if the transport
-      (e.g. SSL) doesn't support half-closes.
+      Close the transport immediately, without waiting for pending operations
+      to complete.  Buffered data will be lost.  No more data will be received.
+      The protocol's :meth:`connection_lost` method will eventually be
+      called with :const:`None` as its argument.
 
    .. method:: can_write_eof()
 
       Return :const:`True` if the transport supports :meth:`write_eof`,
       :const:`False` if not.
 
-   .. method:: abort()
+   .. method:: get_write_buffer_size()
 
-      Close the transport immediately, without waiting for pending operations
-      to complete.  Buffered data will be lost.  No more data will be received.
-      The protocol's :meth:`connection_lost` method will eventually be
-      called with :const:`None` as its argument.
+      Return the current size of the output buffer used by the transport.
 
    .. method:: set_write_buffer_limits(high=None, low=None)
 
@@ -767,9 +748,26 @@ Methods of writable streaming transports: WriteTransport
       reduces opportunities for doing I/O and computation
       concurrently.
 
-   .. method:: get_write_buffer_size()
+   .. method:: write(data)
 
-      Return the current size of the output buffer used by the transport.
+      Write some *data* bytes to the transport.
+
+      This method does not block; it buffers the data and arranges for it
+      to be sent out asynchronously.
+
+   .. method:: writelines(list_of_data)
+
+      Write a list (or any iterable) of data bytes to the transport.
+      This is functionally equivalent to calling :meth:`write` on each
+      element yielded by the iterable, but may be implemented more efficiently.
+
+   .. method:: write_eof()
+
+      Close the write end of the transport after flushing buffered data.
+      Data may still be received.
+
+      This method can raise :exc:`NotImplementedError` if the transport
+      (e.g. SSL) doesn't support half-closes.
 
 
 Methods of datagram transports
@@ -837,180 +835,111 @@ Methods of subprocess transports
       On Windows, this method is an alias for :meth:`terminate`.
 
 
-Task functions
---------------
-
-.. function:: as_completed(fs, *, loop=None, timeout=None)
-
-   Return an iterator whose values, when waited for, are
-   :class:`~concurrent.futures.Future` instances.
-
-   Raises :exc:`TimeoutError` if the timeout occurs before all Futures are done.
-
-   Example::
-
-       for f in as_completed(fs):
-           result = yield from f  # The 'yield from' may raise
-           # Use result
-
-   .. note::
-
-      The futures ``f`` are not necessarily members of fs.
-
-.. function:: async(coro_or_future, *, loop=None)
-
-   Wrap a :ref:`coroutine <coroutine>` in a future.
-
-   If the argument is a :class:`~concurrent.futures.Future`, it is returned
-   directly.
-
-.. function:: gather(*coros_or_futures, loop=None, return_exceptions=False)
-
-   Return a future aggregating results from the given coroutines or futures.
-
-   All futures must share the same event loop.  If all the tasks are done
-   successfully, the returned future's result is the list of results (in the
-   order of the original sequence, not necessarily the order of results
-   arrival).  If *result_exception* is True, exceptions in the tasks are
-   treated the same as successful results, and gathered in the result list;
-   otherwise, the first raised exception will be immediately propagated to the
-   returned future.
+Stream reader and writer
+------------------------
 
-   Cancellation: if the outer Future is cancelled, all children (that have not
-   completed yet) are also cancelled.  If any child is cancelled, this is
-   treated as if it raised :exc:`~concurrent.futures.CancelledError` -- the
-   outer Future is *not* cancelled in this case.  (This is to prevent the
-   cancellation of one child to cause other children to be cancelled.)
+.. class:: StreamWriter(transport, protocol, reader, loop)
 
-.. function:: tasks.iscoroutinefunction(func)
+   Wraps a Transport.
 
-   Return ``True`` if *func* is a decorated coroutine function.
+   This exposes :meth:`write`, :meth:`writelines`, :meth:`can_write_eof()`, :meth:`write_eof`, :meth:`get_extra_info` and
+   :meth:`close`.  It adds :meth:`drain` which returns an optional :class:`~concurrent.futures.Future` on which you can
+   wait for flow control.  It also adds a transport attribute which references
+   the :class:`Transport` directly.
 
-.. function:: tasks.iscoroutine(obj)
+   .. attribute:: transport
 
-   Return ``True`` if *obj* is a coroutine object.
+      Transport.
 
-.. function:: sleep(delay, result=None, \*, loop=None)
+   .. method:: close()
 
-   Create a :ref:`coroutine <coroutine>` that completes after a given time
-   (in seconds).
+      Close the transport: see :meth:`BaseTransport.close`.
 
-.. function:: shield(arg, \*, loop=None)
+   .. method:: drain()
 
-   Wait for a future, shielding it from cancellation.
+      This method has an unusual return value.
 
-   The statement::
+      The intended use is to write::
 
-       res = yield from shield(something())
+          w.write(data)
+          yield from w.drain()
 
-   is exactly equivalent to the statement::
+      When there's nothing to wait for, :meth:`drain()` returns ``()``, and the
+      yield-from continues immediately.  When the transport buffer is full (the
+      protocol is paused), :meth:`drain` creates and returns a
+      :class:`~concurrent.futures.Future` and the yield-from will block until
+      that Future is completed, which will happen when the buffer is
+      (partially) drained and the protocol is resumed.
 
-       res = yield from something()
+   .. method:: get_extra_info(name, default=None)
 
-   *except* that if the coroutine containing it is cancelled, the task running
-   in ``something()`` is not cancelled.  From the point of view of
-   ``something()``, the cancellation did not happen.  But its caller is still
-   cancelled, so the yield-from expression still raises
-   :exc:`~concurrent.futures.CancelledError`.  Note: If ``something()`` is
-   cancelled by other means this will still cancel ``shield()``.
+      Return optional transport information: see
+      :meth:`BaseTransport.get_extra_info`.
 
-   If you want to completely ignore cancellation (not recommended) you can
-   combine ``shield()`` with a try/except clause, as follows::
+   .. method:: write(data)
 
-       try:
-           res = yield from shield(something())
-       except CancelledError:
-           res = None
+      Write some *data* bytes to the transport: see
+      :meth:`WriteTransport.write`.
 
-.. function:: wait(fs, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
+   .. method:: writelines(data)
 
-   Wait for the Futures and coroutines given by fs to complete. Coroutines will
-   be wrapped in Tasks.  Returns two sets of
-   :class:`~concurrent.futures.Future`: (done, pending).
+      Write a list (or any iterable) of data bytes to the transport:
+      see :meth:`WriteTransport.writelines`.
 
-   *timeout* can be used to control the maximum number of seconds to wait before
-   returning.  *timeout* can be an int or float.  If *timeout* is not specified
-   or ``None``, there is no limit to the wait time.
+   .. method:: can_write_eof()
 
-   *return_when* indicates when this function should return.  It must be one of
-   the following constants of the :mod`concurrent.futures` module:
+      Return :const:`True` if the transport supports :meth:`write_eof`,
+      :const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
 
-   .. tabularcolumns:: |l|L|
+   .. method:: write_eof()
 
-   +-----------------------------+----------------------------------------+
-   | Constant                    | Description                            |
-   +=============================+========================================+
-   | :const:`FIRST_COMPLETED`    | The function will return when any      |
-   |                             | future finishes or is cancelled.       |
-   +-----------------------------+----------------------------------------+
-   | :const:`FIRST_EXCEPTION`    | The function will return when any      |
-   |                             | future finishes by raising an          |
-   |                             | exception.  If no future raises an     |
-   |                             | exception then it is equivalent to     |
-   |                             | :const:`ALL_COMPLETED`.                |
-   +-----------------------------+----------------------------------------+
-   | :const:`ALL_COMPLETED`      | The function will return when all      |
-   |                             | futures finish or are cancelled.       |
-   +-----------------------------+----------------------------------------+
+      Close the write end of the transport after flushing buffered data:
+      see :meth:`WriteTransport.write_eof`.
 
-   This function returns a :ref:`coroutine <coroutine>`.
 
-   Usage::
+.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
 
-        done, pending = yield from asyncio.wait(fs)
+   .. method:: exception()
 
-   .. note::
+      Get the exception.
 
-      This does not raise :exc:`TimeoutError`! Futures that aren't done when
-      the timeout occurs are returned in the second set.
+   .. method:: feed_eof()
 
+      XXX
 
-Task
-----
+   .. method:: feed_data(data)
 
-.. class:: Task(coro, \*, loop=None)
+      XXX
 
-   A coroutine wrapped in a :class:`~concurrent.futures.Future`.
+   .. method:: set_exception(exc)
 
-   .. classmethod:: all_tasks(loop=None)
+      Set the exception.
 
-      Return a set of all tasks for an event loop.
+   .. method:: set_transport(transport)
 
-      By default all tasks for the current event loop are returned.
+      Set the transport.
 
-   .. method:: cancel()
+   .. method:: read(n=-1)
 
-      Cancel the task.
+      XXX
 
-   .. method:: get_stack(self, \*, limit=None)
+      This method returns a :ref:`coroutine <coroutine>`.
 
-      Return the list of stack frames for this task's coroutine.
+   .. method:: readline()
 
-      If the coroutine is active, this returns the stack where it is suspended.
-      If the coroutine has completed successfully or was cancelled, this
-      returns an empty list.  If the coroutine was terminated by an exception,
-      this returns the list of traceback frames.
+      XXX
 
-      The frames are always ordered from oldest to newest.
+      This method returns a :ref:`coroutine <coroutine>`.
 
-      The optional limit gives the maximum nummber of frames to return; by
-      default all available frames are returned.  Its meaning differs depending
-      on whether a stack or a traceback is returned: the newest frames of a
-      stack are returned, but the oldest frames of a traceback are returned.
-      (This matches the behavior of the traceback module.)
+   .. method:: readexactly(n)
 
-      For reasons beyond our control, only one stack frame is returned for a
-      suspended coroutine.
+      XXX
 
-   .. method:: print_stack(\*, limit=None, file=None)
+      This method returns a :ref:`coroutine <coroutine>`.
 
-      Print the stack or traceback for this task's coroutine.
 
-      This produces output similar to that of the traceback module, for the
-      frames retrieved by get_stack().  The limit argument is passed to
-      get_stack().  The file argument is an I/O stream to which the output
-      goes; by default it goes to sys.stderr.
 
+.. _protocol:
 
 Protocols
 ---------
@@ -1032,161 +961,180 @@ call them yourself, unless you are implementing a transport.
    are interested.
 
 
-Stream reader and writer
-------------------------
-
-.. class:: StreamWriter(transport, protocol, reader, loop)
-
-   Wraps a Transport.
+Protocol classes
+^^^^^^^^^^^^^^^^
 
-   This exposes :meth:`write`, :meth:`writelines`, :meth:`can_write_eof()`, :meth:`write_eof`, :meth:`get_extra_info` and
-   :meth:`close`.  It adds :meth:`drain` which returns an optional :class:`~concurrent.futures.Future` on which you can
-   wait for flow control.  It also adds a transport attribute which references
-   the :class:`Transport` directly.
+.. class:: Protocol
 
-   .. attribute:: transport
+   The base class for implementing streaming protocols (for use with
+   e.g. TCP and SSL transports).
 
-      Transport.
+.. class:: DatagramProtocol
 
-   .. method:: close()
+   The base class for implementing datagram protocols (for use with
+   e.g. UDP transports).
 
-      Close the transport: see :meth:`BaseTransport.close`.
+.. class:: SubprocessProtocol
 
-   .. method:: drain()
+   The base class for implementing protocols communicating with child
+   processes (through a set of unidirectional pipes).
 
-      This method has an unusual return value.
 
-      The intended use is to write::
+Connection callbacks
+^^^^^^^^^^^^^^^^^^^^
 
-          w.write(data)
-          yield from w.drain()
+These callbacks may be called on :class:`Protocol` and
+:class:`SubprocessProtocol` instances:
 
-      When there's nothing to wait for, :meth:`drain()` returns ``()``, and the
-      yield-from continues immediately.  When the transport buffer is full (the
-      protocol is paused), :meth:`drain` creates and returns a
-      :class:`~concurrent.futures.Future` and the yield-from will block until
-      that Future is completed, which will happen when the buffer is
-      (partially) drained and the protocol is resumed.
+.. method:: BaseProtocol.connection_made(transport)
 
-   .. method:: get_extra_info(name, default=None)
+   Called when a connection is made.
 
-      Return optional transport information: see
-      :meth:`BaseTransport.get_extra_info`.
+   The *transport* argument is the transport representing the
+   connection.  You are responsible for storing it somewhere
+   (e.g. as an attribute) if you need to.
 
-   .. method:: write(data)
+.. method:: BaseProtocol.connection_lost(exc)
 
-      Write some *data* bytes to the transport: see
-      :meth:`WriteTransport.write`.
+   Called when the connection is lost or closed.
 
-   .. method:: writelines(data)
+   The argument is either an exception object or :const:`None`.
+   The latter means a regular EOF is received, or the connection was
+   aborted or closed by this side of the connection.
 
-      Write a list (or any iterable) of data bytes to the transport:
-      see :meth:`WriteTransport.writelines`.
+:meth:`connection_made` and :meth:`connection_lost` are called exactly once
+per successful connection.  All other callbacks will be called between those
+two methods, which allows for easier resource management in your protocol
+implementation.
 
-   .. method:: can_write_eof()
+The following callbacks may be called only on :class:`SubprocessProtocol`
+instances:
 
-      Return :const:`True` if the transport supports :meth:`write_eof`,
-      :const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
+.. method:: SubprocessProtocol.pipe_data_received(fd, data)
 
-   .. method:: write_eof()
+   Called when the child process writes data into its stdout or stderr pipe.
+   *fd* is the integer file descriptor of the pipe.  *data* is a non-empty
+   bytes object containing the data.
 
-      Close the write end of the transport after flushing buffered data:
-      see :meth:`WriteTransport.write_eof`.
+.. method:: SubprocessProtocol.pipe_connection_lost(fd, exc)
 
+   Called when one of the pipes communicating with the child process
+   is closed.  *fd* is the integer file descriptor that was closed.
 
-.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
+.. method:: SubprocessProtocol.process_exited()
 
-   .. method:: exception()
+   Called when the child process has exited.
 
-      Get the exception.
 
-   .. method:: feed_eof()
+Data reception callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-      XXX
+Streaming protocols
+"""""""""""""""""""
 
-   .. method:: feed_data(data)
+The following callbacks are called on :class:`Protocol` instances:
 
-      XXX
+.. method:: Protocol.data_received(data)
 
-   .. method:: set_exception(exc)
+   Called when some data is received.  *data* is a non-empty bytes object
+   containing the incoming data.
 
-      Set the exception.
+   .. note::
+      Whether the data is buffered, chunked or reassembled depends on
+      the transport.  In general, you shouldn't rely on specific semantics
+      and instead make your parsing generic and flexible enough.  However,
+      data is always received in the correct order.
 
-   .. method:: set_transport(transport)
+.. method:: Protocol.eof_received()
 
-      Set the transport.
+   Calls when the other end signals it won't send any more data
+   (for example by calling :meth:`write_eof`, if the other end also uses
+   asyncio).
 
-   .. method:: read(n=-1)
+   This method may return a false value (including None), in which case
+   the transport will close itself.  Conversely, if this method returns a
+   true value, closing the transport is up to the protocol.  Since the
+   default implementation returns None, it implicitly closes the connection.
 
-      XXX
+   .. note::
+      Some transports such as SSL don't support half-closed connections,
+      in which case returning true from this method will not prevent closing
+      the connection.
 
-      This method returns a :ref:`coroutine <coroutine>`.
+:meth:`data_received` can be called an arbitrary number of times during
+a connection.  However, :meth:`eof_received` is called at most once
+and, if called, :meth:`data_received` won't be called after it.
 
-   .. method:: readline()
+Datagram protocols
+""""""""""""""""""
 
-      XXX
+The following callbacks are called on :class:`DatagramProtocol` instances.
 
-      This method returns a :ref:`coroutine <coroutine>`.
+.. method:: DatagramProtocol.datagram_received(data, addr)
 
-   .. method:: readexactly(n)
+   Called when a datagram is received.  *data* is a bytes object containing
+   the incoming data.  *addr* is the address of the peer sending the data;
+   the exact format depends on the transport.
 
-      XXX
+.. method:: DatagramProtocol.error_received(exc)
 
-      This method returns a :ref:`coroutine <coroutine>`.
+   Called when a previous send or receive operation raises an
+   :class:`OSError`.  *exc* is the :class:`OSError` instance.
 
+   This method is called in rare conditions, when the transport (e.g. UDP)
+   detects that a datagram couldn't be delivered to its recipient.
+   In many conditions though, undeliverable datagrams will be silently
+   dropped.
 
 
-.. _coroutine:
+Flow control callbacks
+^^^^^^^^^^^^^^^^^^^^^^
 
-Coroutines
-----------
+These callbacks may be called on :class:`Protocol` and
+:class:`SubprocessProtocol` instances:
 
-A coroutine is a generator that follows certain conventions.  For
-documentation purposes, all coroutines should be decorated with
-``@asyncio.coroutine``, but this cannot be strictly enforced.
+.. method:: BaseProtocol.pause_writing()
 
-Coroutines use the ``yield from`` syntax introduced in :pep:`380`,
-instead of the original ``yield`` syntax.
+   Called when the transport's buffer goes over the high-water mark.
 
-The word "coroutine", like the word "generator", is used for two
-different (though related) concepts:
+.. method:: BaseProtocol.resume_writing()
 
-- The function that defines a coroutine (a function definition
-  decorated with ``asyncio.coroutine``).  If disambiguation is needed
-  we will call this a *coroutine function*.
+   Called when the transport's buffer drains below the low-water mark.
 
-- The object obtained by calling a coroutine function.  This object
-  represents a computation or an I/O operation (usually a combination)
-  that will complete eventually.  If disambiguation is needed we will
-  call it a *coroutine object*.
 
-Things a coroutine can do:
+:meth:`pause_writing` and :meth:`resume_writing` calls are paired --
+:meth:`pause_writing` is called once when the buffer goes strictly over
+the high-water mark (even if subsequent writes increases the buffer size
+even more), and eventually :meth:`resume_writing` is called once when the
+buffer size reaches the low-water mark.
 
-- ``result = yield from future`` -- suspends the coroutine until the
-  future is done, then returns the future's result, or raises an
-  exception, which will be propagated.  (If the future is cancelled,
-  it will raise a ``CancelledError`` exception.)  Note that tasks are
-  futures, and everything said about futures also applies to tasks.
+.. note::
+   If the buffer size equals the high-water mark,
+   :meth:`pause_writing` is not called -- it must go strictly over.
+   Conversely, :meth:`resume_writing` is called when the buffer size is
+   equal or lower than the low-water mark.  These end conditions
+   are important to ensure that things go as expected when either
+   mark is zero.
 
-- ``result = yield from coroutine`` -- wait for another coroutine to
-  produce a result (or raise an exception, which will be propagated).
-  The ``coroutine`` expression must be a *call* to another coroutine.
 
-- ``return expression`` -- produce a result to the coroutine that is
-  waiting for this one using ``yield from``.
+Protocols
+---------
 
-- ``raise exception`` -- raise an exception in the coroutine that is
-  waiting for this one using ``yield from``.
+:mod:`asyncio` provides base classes that you can subclass to implement
+your network protocols.  Those classes are used in conjunction with
+:ref:`transports <transport>` (see below): the protocol parses incoming
+data and asks for the writing of outgoing data, while the transport is
+responsible for the actual I/O and buffering.
 
-Calling a coroutine does not start its code running -- it is just a
-generator, and the coroutine object returned by the call is really a
-generator object, which doesn't do anything until you iterate over it.
-In the case of a coroutine object, there are two basic ways to start
-it running: call ``yield from coroutine`` from another coroutine
-(assuming the other coroutine is already running!), or convert it to a
-:class:`Task`.
+When subclassing a protocol class, it is recommended you override certain
+methods.  Those methods are callbacks: they will be called by the transport
+on certain events (for example when some data is received); you shouldn't
+call them yourself, unless you are implementing a transport.
 
-Coroutines (and tasks) can only run when the event loop is running.
+.. note::
+   All callbacks have default implementations, which are empty.  Therefore,
+   you only need to implement the callbacks for the events in which you
+   are interested.
 
 
 Server
@@ -1205,6 +1153,58 @@ Server
       Coroutine to wait until service is closed.
 
 
+Network functions
+-----------------
+
+.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+   A wrapper for create_connection() returning a (reader, writer) pair.
+
+   The reader returned is a StreamReader instance; the writer is a
+   :class:`Transport`.
+
+   The arguments are all the usual arguments to
+   :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
+   common are positional host and port, with various optional keyword arguments
+   following.
+
+   Additional optional keyword arguments are *loop* (to set the event loop
+   instance to use) and *limit* (to set the buffer limit passed to the
+   StreamReader).
+
+   (If you want to customize the :class:`StreamReader` and/or
+   :class:`StreamReaderProtocol` classes, just copy the code -- there's really
+   nothing special here except some convenience.)
+
+   This function returns a :ref:`coroutine <coroutine>`.
+
+.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+   Start a socket server, call back for each client connected.
+
+   The first parameter, *client_connected_cb*, takes two parameters:
+   *client_reader*, *client_writer*.  *client_reader* is a
+   :class:`StreamReader` object, while *client_writer* is a
+   :class:`StreamWriter` object.  This parameter can either be a plain callback
+   function or a :ref:`coroutine <coroutine>`; if it is a coroutine, it will be
+   automatically converted into a :class:`Task`.
+
+   The rest of the arguments are all the usual arguments to
+   :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
+   common are positional host and port, with various optional keyword arguments
+   following.  The return value is the same as
+   :meth:`~BaseEventLoop.create_server()`.
+
+   Additional optional keyword arguments are *loop* (to set the event loop
+   instance to use) and *limit* (to set the buffer limit passed to the
+   :class:`StreamReader`).
+
+   The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
+   a :class:`AbstractServer` object which can be used to stop the service.
+
+   This function returns a :ref:`coroutine <coroutine>`.
+
+
 .. _sync:
 
 Synchronization primitives