Skip to content

C
cpython
Kaydet (Commit) b3be72ca authored tarafından Victor Stinner's avatar Victor Stinner
Dosyalara gözat
Seçenekler

asyncio doc: reorder sections

üst 34d8df51
Hide whitespace changes
Inline Side-by-side
Showing with 428 additions and 428 deletions
Doc/library/asyncio.rst
Dosyayı görüntüle @ b3be72ca
......@@ -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
--------------
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
---------
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment