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 ...@@ -326,28 +326,6 @@ Creating connections
to bind the socket to locally. The *local_host* and *local_port* to bind the socket to locally. The *local_host* and *local_port*
are looked up using getaddrinfo(), similarly to *host* and *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 Resolve name
^^^^^^^^^^^^ ^^^^^^^^^^^^
...@@ -382,235 +360,255 @@ Run subprocesses asynchronously using the :mod:`subprocess` module. ...@@ -382,235 +360,255 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
See the constructor of the :class:`subprocess.Popen` class for parameters. 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 .. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
:class:`Transport`.
The arguments are all the usual arguments to Register write pipe in eventloop.
: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 *protocol_factory* should instantiate object with :class:`BaseProtocol`
instance to use) and *limit* (to set the buffer limit passed to the interface. Pipe is file-like object already switched to nonblocking.
StreamReader). Return pair (transport, protocol), where transport support
:class:`WriteTransport` interface.
(If you want to customize the :class:`StreamReader` and/or This method returns a :ref:`coroutine <coroutine>`.
: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) .. _coroutine:
Start a socket server, call back for each client connected. Coroutines
----------
The first parameter, *client_connected_cb*, takes two parameters: A coroutine is a generator that follows certain conventions. For
*client_reader*, *client_writer*. *client_reader* is a documentation purposes, all coroutines should be decorated with
:class:`StreamReader` object, while *client_writer* is a ``@asyncio.coroutine``, but this cannot be strictly enforced.
: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 Coroutines use the ``yield from`` syntax introduced in :pep:`380`,
:meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most instead of the original ``yield`` syntax.
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 The word "coroutine", like the word "generator", is used for two
instance to use) and *limit* (to set the buffer limit passed to the different (though related) concepts:
:class:`StreamReader`).
The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e. - The function that defines a coroutine (a function definition
a :class:`AbstractServer` object which can be used to stop the service. 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 - ``return expression`` -- produce a result to the coroutine that is
your network protocols. Those classes are used in conjunction with waiting for this one using ``yield from``.
: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.
When subclassing a protocol class, it is recommended you override certain - ``raise exception`` -- raise an exception in the coroutine that is
methods. Those methods are callbacks: they will be called by the transport waiting for this one using ``yield from``.
on certain events (for example when some data is received); you shouldn't
call them yourself, unless you are implementing a transport.
.. note:: Calling a coroutine does not start its code running -- it is just a
All callbacks have default implementations, which are empty. Therefore, generator, and the coroutine object returned by the call is really a
you only need to implement the callbacks for the events in which you generator object, which doesn't do anything until you iterate over it.
are interested. 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 .. class:: Task(coro, \*, loop=None)
e.g. TCP and SSL transports).
.. class:: DatagramProtocol A coroutine wrapped in a :class:`~concurrent.futures.Future`.
The base class for implementing datagram protocols (for use with .. classmethod:: all_tasks(loop=None)
e.g. UDP transports).
.. class:: SubprocessProtocol Return a set of all tasks for an event loop.
The base class for implementing protocols communicating with child By default all tasks for the current event loop are returned.
processes (through a set of unidirectional pipes).
.. method:: cancel()
Connection callbacks Cancel the task.
^^^^^^^^^^^^^^^^^^^^
These callbacks may be called on :class:`Protocol` and .. method:: get_stack(self, \*, limit=None)
:class:`SubprocessProtocol` instances:
.. 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 The frames are always ordered from oldest to newest.
connection. You are responsible for storing it somewhere
(e.g. as an attribute) if you need to.
.. 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`. .. method:: print_stack(\*, limit=None, file=None)
The latter means a regular EOF is received, or the connection was
aborted or closed by this side of the connection.
:meth:`connection_made` and :meth:`connection_lost` are called exactly once Print the stack or traceback for this task's coroutine.
per successful connection. All other callbacks will be called between those
two methods, which allows for easier resource management in your protocol
implementation.
The following callbacks may be called only on :class:`SubprocessProtocol` This produces output similar to that of the traceback module, for the
instances: 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. Task functions
*fd* is the integer file descriptor of the pipe. *data* is a non-empty --------------
bytes object containing the data.
.. 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 Return an iterator whose values, when waited for, are
is closed. *fd* is the integer file descriptor that was closed. :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 If the argument is a :class:`~concurrent.futures.Future`, it is returned
containing the incoming data. directly.
.. note:: .. function:: gather(*coros_or_futures, loop=None, return_exceptions=False)
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:: 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 All futures must share the same event loop. If all the tasks are done
(for example by calling :meth:`write_eof`, if the other end also uses successfully, the returned future's result is the list of results (in the
asyncio). 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 Cancellation: if the outer Future is cancelled, all children (that have not
the transport will close itself. Conversely, if this method returns a completed yet) are also cancelled. If any child is cancelled, this is
true value, closing the transport is up to the protocol. Since the treated as if it raised :exc:`~concurrent.futures.CancelledError` -- the
default implementation returns None, it implicitly closes the connection. 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:: .. function:: tasks.iscoroutinefunction(func)
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.
:meth:`data_received` can be called an arbitrary number of times during Return ``True`` if *func* is a decorated coroutine function.
a connection. However, :meth:`eof_received` is called at most once
and, if called, :meth:`data_received` won't be called after it.
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 Create a :ref:`coroutine <coroutine>` that completes after a given time
the incoming data. *addr* is the address of the peer sending the data; (in seconds).
the exact format depends on the transport.
.. method:: DatagramProtocol.error_received(exc) .. function:: shield(arg, \*, loop=None)
Called when a previous send or receive operation raises an Wait for a future, shielding it from cancellation.
:class:`OSError`. *exc* is the :class:`OSError` instance.
This method is called in rare conditions, when the transport (e.g. UDP) The statement::
detects that a datagram couldn't be delivered to its recipient.
In many conditions though, undeliverable datagrams will be silently
dropped.
res = yield from shield(something())
Flow control callbacks is exactly equivalent to the statement::
^^^^^^^^^^^^^^^^^^^^^^
These callbacks may be called on :class:`Protocol` and res = yield from something()
:class:`SubprocessProtocol` instances:
.. 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 -- *timeout* can be used to control the maximum number of seconds to wait before
:meth:`pause_writing` is called once when the buffer goes strictly over returning. *timeout* can be an int or float. If *timeout* is not specified
the high-water mark (even if subsequent writes increases the buffer size or ``None``, there is no limit to the wait time.
even more), and eventually :meth:`resume_writing` is called once when the
buffer size reaches the low-water mark.
.. note:: *return_when* indicates when this function should return. It must be one of
If the buffer size equals the high-water mark, the following constants of the :mod`concurrent.futures` module:
:meth:`pause_writing` is not called -- it must go strictly over.
Conversely, :meth:`resume_writing` is called when the buffer size is .. tabularcolumns:: |l|L|
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. | 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: .. _transport:
...@@ -714,38 +712,21 @@ Methods of writable streaming transports: WriteTransport ...@@ -714,38 +712,21 @@ Methods of writable streaming transports: WriteTransport
Interface for write-only transports. Interface for write-only transports.
.. method:: write(data) .. method:: abort()
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 Close the transport immediately, without waiting for pending operations
(e.g. SSL) doesn't support half-closes. 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() .. method:: can_write_eof()
Return :const:`True` if the transport supports :meth:`write_eof`, Return :const:`True` if the transport supports :meth:`write_eof`,
:const:`False` if not. :const:`False` if not.
.. method:: abort() .. method:: get_write_buffer_size()
Close the transport immediately, without waiting for pending operations Return the current size of the output buffer used by the transport.
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:: set_write_buffer_limits(high=None, low=None) .. method:: set_write_buffer_limits(high=None, low=None)
...@@ -767,9 +748,26 @@ Methods of writable streaming transports: WriteTransport ...@@ -767,9 +748,26 @@ Methods of writable streaming transports: WriteTransport
reduces opportunities for doing I/O and computation reduces opportunities for doing I/O and computation
concurrently. 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 Methods of datagram transports
...@@ -837,180 +835,111 @@ Methods of subprocess transports ...@@ -837,180 +835,111 @@ Methods of subprocess transports
On Windows, this method is an alias for :meth:`terminate`. 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 Wraps a Transport.
:class:`~concurrent.futures.Future` instances.
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): Transport.
result = yield from f # The 'yield from' may raise
# Use result
.. 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 The intended use is to write::
directly.
.. 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 .. method:: get_extra_info(name, default=None)
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.
Cancellation: if the outer Future is cancelled, all children (that have not Return optional transport information: see
completed yet) are also cancelled. If any child is cancelled, this is :meth:`BaseTransport.get_extra_info`.
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.)
.. 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 Return :const:`True` if the transport supports :meth:`write_eof`,
(in seconds). :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 .. method:: feed_eof()
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()``.
If you want to completely ignore cancellation (not recommended) you can XXX
combine ``shield()`` with a try/except clause, as follows::
try: .. method:: feed_data(data)
res = yield from shield(something())
except CancelledError:
res = None
.. 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 .. method:: set_exception(exc)
be wrapped in Tasks. Returns two sets of
:class:`~concurrent.futures.Future`: (done, pending).
*timeout* can be used to control the maximum number of seconds to wait before Set the exception.
returning. *timeout* can be an int or float. If *timeout* is not specified
or ``None``, there is no limit to the wait time.
*return_when* indicates when this function should return. It must be one of .. method:: set_transport(transport)
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.
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. XXX
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 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 .. method:: readexactly(n)
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.)
For reasons beyond our control, only one stack frame is returned for a XXX
suspended coroutine.
.. 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 Protocols
--------- ---------
...@@ -1032,161 +961,180 @@ call them yourself, unless you are implementing a transport. ...@@ -1032,161 +961,180 @@ call them yourself, unless you are implementing a transport.
are interested. are interested.
Stream reader and writer Protocol classes
------------------------ ^^^^^^^^^^^^^^^^
.. class:: StreamWriter(transport, protocol, reader, loop)
Wraps a Transport.
This exposes :meth:`write`, :meth:`writelines`, :meth:`can_write_eof()`, :meth:`write_eof`, :meth:`get_extra_info` and .. class:: Protocol
: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.
.. 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) These callbacks may be called on :class:`Protocol` and
yield from w.drain() :class:`SubprocessProtocol` instances:
When there's nothing to wait for, :meth:`drain()` returns ``()``, and the .. method:: BaseProtocol.connection_made(transport)
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:: get_extra_info(name, default=None) Called when a connection is made.
Return optional transport information: see The *transport* argument is the transport representing the
:meth:`BaseTransport.get_extra_info`. 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 Called when the connection is lost or closed.
:meth:`WriteTransport.write`.
.. 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: :meth:`connection_made` and :meth:`connection_lost` are called exactly once
see :meth:`WriteTransport.writelines`. 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`, .. method:: SubprocessProtocol.pipe_data_received(fd, data)
:const:`False` if not. See :meth:`WriteTransport.can_write_eof`.
.. 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: .. method:: SubprocessProtocol.pipe_connection_lost(fd, exc)
see :meth:`WriteTransport.write_eof`.
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 .. method:: BaseProtocol.pause_writing()
documentation purposes, all coroutines should be decorated with
``@asyncio.coroutine``, but this cannot be strictly enforced.
Coroutines use the ``yield from`` syntax introduced in :pep:`380`, Called when the transport's buffer goes over the high-water mark.
instead of the original ``yield`` syntax.
The word "coroutine", like the word "generator", is used for two .. method:: BaseProtocol.resume_writing()
different (though related) concepts:
- The function that defines a coroutine (a function definition Called when the transport's buffer drains below the low-water mark.
decorated with ``asyncio.coroutine``). If disambiguation is needed
we will call this a *coroutine function*.
- 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 .. note::
future is done, then returns the future's result, or raises an If the buffer size equals the high-water mark,
exception, which will be propagated. (If the future is cancelled, :meth:`pause_writing` is not called -- it must go strictly over.
it will raise a ``CancelledError`` exception.) Note that tasks are Conversely, :meth:`resume_writing` is called when the buffer size is
futures, and everything said about futures also applies to tasks. 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 Protocols
waiting for this one using ``yield from``. ---------
- ``raise exception`` -- raise an exception in the coroutine that is :mod:`asyncio` provides base classes that you can subclass to implement
waiting for this one using ``yield from``. 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 When subclassing a protocol class, it is recommended you override certain
generator, and the coroutine object returned by the call is really a methods. Those methods are callbacks: they will be called by the transport
generator object, which doesn't do anything until you iterate over it. on certain events (for example when some data is received); you shouldn't
In the case of a coroutine object, there are two basic ways to start call them yourself, unless you are implementing a transport.
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. .. 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 Server
...@@ -1205,6 +1153,58 @@ Server ...@@ -1205,6 +1153,58 @@ Server
Coroutine to wait until service is closed. 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: .. _sync:
Synchronization primitives 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