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
^^^^^^^^^^^^
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:
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)
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
On Windows, this method is an alias for :meth:`terminate`.
-Task functions
---------------
+Stream reader and writer
+------------------------
-.. function:: as_completed(fs, *, loop=None, timeout=None)
+.. class:: StreamWriter(transport, protocol, reader, loop)
- Return an iterator whose values, when waited for, are
- :class:`~concurrent.futures.Future` instances.
+ Wraps a Transport.
- Raises :exc:`TimeoutError` if the timeout occurs before all Futures are done.
+ 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.
- Example::
+ .. attribute:: transport
- for f in as_completed(fs):
- result = yield from f # The 'yield from' may raise
- # Use result
+ Transport.
- .. note::
+ .. method:: close()
- The futures ``f`` are not necessarily members of fs.
+ Close the transport: see :meth:`BaseTransport.close`.
-.. function:: async(coro_or_future, *, loop=None)
+ .. method:: drain()
- Wrap a :ref:`coroutine <coroutine>` in a future.
+ This method has an unusual return value.
- If the argument is a :class:`~concurrent.futures.Future`, it is returned
- directly.
+ The intended use is to write::
-.. function:: gather(*coros_or_futures, loop=None, return_exceptions=False)
+ w.write(data)
+ yield from w.drain()
- Return a future aggregating results from the given coroutines or futures.
+ 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.
- 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.
+ .. method:: get_extra_info(name, default=None)
- 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.)
+ Return optional transport information: see
+ :meth:`BaseTransport.get_extra_info`.
-.. function:: tasks.iscoroutinefunction(func)
+ .. method:: write(data)
- Return ``True`` if *func* is a decorated coroutine function.
+ Write some *data* bytes to the transport: see
+ :meth:`WriteTransport.write`.
-.. function:: tasks.iscoroutine(obj)
+ .. method:: writelines(data)
- Return ``True`` if *obj* is a coroutine object.
+ Write a list (or any iterable) of data bytes to the transport:
+ see :meth:`WriteTransport.writelines`.
-.. function:: sleep(delay, result=None, \*, loop=None)
+ .. method:: can_write_eof()
- Create a :ref:`coroutine <coroutine>` that completes after a given time
- (in seconds).
+ Return :const:`True` if the transport supports :meth:`write_eof`,
+ :const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
-.. function:: shield(arg, \*, loop=None)
+ .. method:: write_eof()
- Wait for a future, shielding it from cancellation.
+ Close the write end of the transport after flushing buffered data:
+ see :meth:`WriteTransport.write_eof`.
- The statement::
- res = yield from shield(something())
+.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
- is exactly equivalent to the statement::
+ .. method:: exception()
- res = yield from something()
+ Get the exception.
- *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()``.
+ .. method:: feed_eof()
- If you want to completely ignore cancellation (not recommended) you can
- combine ``shield()`` with a try/except clause, as follows::
+ XXX
- try:
- res = yield from shield(something())
- except CancelledError:
- res = None
+ .. method:: feed_data(data)
-.. function:: wait(fs, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
+ XXX
- 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).
+ .. method:: set_exception(exc)
- *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.
+ Set the exception.
- *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.
-
-
-Task
-----
-
-.. class:: Task(coro, \*, loop=None)
-
- A coroutine wrapped in a :class:`~concurrent.futures.Future`.
-
- .. classmethod:: all_tasks(loop=None)
-
- 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
---------
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
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
projects / python / commitdiff