[Python-checkins] cpython (3.4): Issue #21680: Document asyncio event loops
victor.stinner
python-checkins at python.org
Tue Jul 8 23:43:21 CEST 2014
http://hg.python.org/cpython/rev/3f1381e3a68f
changeset: 91612:3f1381e3a68f
branch: 3.4
parent: 91609:66f06fbf8a2f
user: Victor Stinner <victor.stinner at gmail.com>
date: Tue Jul 08 23:42:38 2014 +0200
summary:
Issue #21680: Document asyncio event loops
files:
Doc/library/asyncio-eventloop.rst | 82 +-
Doc/library/asyncio-eventloop.rst | 762 ++--------------
Doc/library/asyncio-subprocess.rst | 20 +-
Doc/library/asyncio.rst | 1 +
4 files changed, 132 insertions(+), 733 deletions(-)
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -2,8 +2,8 @@
.. _asyncio-event-loop:
-Event loops
-===========
+Base Event Loop
+===============
The event loop is the central execution device provided by :mod:`asyncio`.
It provides multiple facilities, amongst which:
@@ -18,78 +18,9 @@
* Delegating costly function calls to a pool of threads.
-Event loop policies and the default policy
-------------------------------------------
+.. class:: BaseEventLoop
-Event loop management is abstracted with a *policy* pattern, to provide maximal
-flexibility for custom platforms and frameworks. Throughout the execution of a
-process, a single global policy object manages the event loops available to the
-process based on the calling context. A policy is an object implementing the
-:class:`AbstractEventLoopPolicy` interface.
-
-For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
-
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
-:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
-event loops managed by the default policy.
-
-Event loop functions
---------------------
-
-The following functions are convenient shortcuts to accessing the methods of the
-global policy. Note that this provides access to the default policy, unless an
-alternative policy was set by calling :func:`set_event_loop_policy` earlier in
-the execution of the process.
-
-.. function:: get_event_loop()
-
- Equivalent to calling ``get_event_loop_policy().get_event_loop()``.
-
-.. function:: set_event_loop(loop)
-
- Equivalent to calling ``get_event_loop_policy().set_event_loop(loop)``.
-
-.. function:: new_event_loop()
-
- Equivalent to calling ``get_event_loop_policy().new_event_loop()``.
-
-Event loop policy interface
----------------------------
-
-An event loop policy must implement the following interface:
-
-.. class:: AbstractEventLoopPolicy
-
- .. method:: get_event_loop()
-
- Get the event loop for the current context. Returns an event loop object
- implementing the :class:`BaseEventLoop` interface, or raises an exception in case
- no event loop has been set for the current context and the current policy
- does not specify to create one. It should never return ``None``.
-
- .. method:: set_event_loop(loop)
-
- Set the event loop for the current context to *loop*.
-
- .. method:: new_event_loop()
-
- Create and return a new event loop object according to this policy's rules.
- If there's need to set this loop as the event loop for the current context,
- :meth:`set_event_loop` must be called explicitly.
-
-Access to the global loop policy
---------------------------------
-
-.. function:: get_event_loop_policy()
-
- Get the current event loop policy.
-
-.. function:: set_event_loop_policy(policy)
-
- Set the current event loop policy. If *policy* is ``None``, the default
- policy is restored.
+ Base class of event loops.
Run an event loop
-----------------
@@ -375,7 +306,6 @@
Availability: UNIX.
-
Watch file descriptors
----------------------
@@ -624,7 +554,6 @@
The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
-
Server
------
@@ -652,7 +581,8 @@
.. method:: cancel()
- Cancel the call.
+ Cancel the call.
+
.. _asyncio-hello-world-callback:
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloops.rst
copy from Doc/library/asyncio-eventloop.rst
copy to Doc/library/asyncio-eventloops.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -1,40 +1,8 @@
.. currentmodule:: asyncio
-.. _asyncio-event-loop:
-
Event loops
===========
-The event loop is the central execution device provided by :mod:`asyncio`.
-It provides multiple facilities, amongst which:
-
-* Registering, executing and cancelling delayed calls (timeouts).
-
-* Creating client and server :ref:`transports <asyncio-transport>` for various
- kinds of communication.
-
-* Launching subprocesses and the associated :ref:`transports
- <asyncio-transport>` for communication with an external program.
-
-* Delegating costly function calls to a pool of threads.
-
-Event loop policies and the default policy
-------------------------------------------
-
-Event loop management is abstracted with a *policy* pattern, to provide maximal
-flexibility for custom platforms and frameworks. Throughout the execution of a
-process, a single global policy object manages the event loops available to the
-process based on the calling context. A policy is an object implementing the
-:class:`AbstractEventLoopPolicy` interface.
-
-For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
-
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
-:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
-event loops managed by the default policy.
-
Event loop functions
--------------------
@@ -55,6 +23,121 @@
Equivalent to calling ``get_event_loop_policy().new_event_loop()``.
+
+Available event loops
+---------------------
+
+asyncio currently provides two implementations of event loops:
+:class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
+
+.. class:: SelectorEventLoop
+
+ Event loop based on the :mod:`selectors` module. Subclass of
+ :class:`BaseEventLoop`.
+
+ Use the most efficient selector available on the platform.
+
+.. class:: ProactorEventLoop
+
+ Proactor event loop for Windows using "I/O Completion Ports" aka IOCP.
+ Subclass of :class:`BaseEventLoop`.
+
+ Availability: Windows.
+
+ .. seealso::
+
+ `MSDN documentation on I/O Completion Ports
+ <http://msdn.microsoft.com/en-us/library/windows/desktop/aa365198%28v=vs.85%29.aspx>`_.
+
+Example to use a :class:`ProactorEventLoop` on Windows::
+
+ import asyncio, os
+
+ if os.name == 'nt':
+ loop = asyncio.ProactorEventLoop()
+ asyncio.set_event_loop(loop)
+
+
+Platform support
+----------------
+
+The :mod:`asyncio` module has been designed to be portable, but each platform
+still has subtle differences and may not support all :mod:`asyncio` features.
+
+Windows
+^^^^^^^
+
+Common limits of Windows event loops:
+
+- :meth:`~BaseEventLoop.create_unix_server` and
+ :meth:`~BaseEventLoop.create_unix_server` are not supported: specific to UNIX
+- :meth:`~BaseEventLoop.add_signal_handler` and
+ :meth:`~BaseEventLoop.remove_signal_handler` are not supported
+- Pipes are not supported: :meth:`~BaseEventLoop.connect_read_pipe` and
+ :meth:`~BaseEventLoop.connect_write_pipe`
+- :meth:`EventLoopPolicy.set_child_watcher` is not supported
+
+:class:`SelectorEventLoop` specific limits:
+
+- :class:`~selectors.SelectSelector` is used but it only supports sockets,
+ see the `MSDN documentation of select
+ <http://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_.
+- it is not possible to execute subprocesses
+- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` only
+ accept file descriptors of sockets
+
+:class:`ProactorEventLoop` specific limits:
+
+- SSL is not supported: :meth:`~BaseEventLoop.create_connection` and
+ :meth:`~BaseEventLoop.create_server` cannot be used with SSL for example
+- :meth:`~BaseEventLoop.create_datagram_endpoint` (UDP) is not supported
+- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` are
+ not supported
+
+The resolution of the monotonic clock on Windows is usually around 15.6 msec.
+The best resolution is 0.5 msec. The exact resolution depends on the hardware
+(availability of HPET) and the Windows configuration. See :ref:`asyncio delayed
+calls <asyncio-delayed-calls>`.
+
+
+Mac OS X
+^^^^^^^^
+
+Character devices like PTY are only well supported since Mavericks (Mac OS
+10.9). They are not supported at all on Mac OS 10.5 and older.
+
+On Mac OS 10.6, 10.7 and 10.8, the default event loop is
+:class:`SelectorEventLoop` which uses :class:`selectors.KqueueSelector`.
+:class:`selectors.KqueueSelector` does not support character devices on these
+versions. The :class:`SelectorEventLoop` can be used with
+:class:`~selectors.SelectSelector` or :class:`~selectors.PollSelector` to
+support character devices on these versions of Mac OS X. Example::
+
+ import asyncio
+ import selectors
+
+ selector = selectors.SelectSelector()
+ loop = asyncio.SelectorEventLoop(selector)
+ asyncio.set_event_loop(loop)
+
+
+Event loop policies and the default policy
+------------------------------------------
+
+Event loop management is abstracted with a *policy* pattern, to provide maximal
+flexibility for custom platforms and frameworks. Throughout the execution of a
+process, a single global policy object manages the event loops available to the
+process based on the calling context. A policy is an object implementing the
+:class:`AbstractEventLoopPolicy` interface.
+
+For most users of :mod:`asyncio`, policies never have to be dealt with
+explicitly, since the default global policy is sufficient.
+
+The default policy defines context as the current thread, and manages an event
+loop per thread that interacts with :mod:`asyncio`. The module-level functions
+:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
+event loops managed by the default policy.
+
Event loop policy interface
---------------------------
@@ -91,618 +174,3 @@
Set the current event loop policy. If *policy* is ``None``, the default
policy is restored.
-Run an event loop
------------------
-
-.. method:: BaseEventLoop.run_forever()
-
- Run until :meth:`stop` is called.
-
-.. method:: BaseEventLoop.run_until_complete(future)
-
- Run until the :class:`Future` is done.
-
- If the argument is a :ref:`coroutine object <coroutine>`, it is wrapped by
- :func:`async`.
-
- Return the Future's result, or raise its exception.
-
-.. method:: BaseEventLoop.is_running()
-
- Returns running status of event loop.
-
-.. method:: BaseEventLoop.stop()
-
- Stop running the event loop.
-
- Every callback scheduled before :meth:`stop` is called will run.
- Callback scheduled after :meth:`stop` is called won't. However, those
- callbacks will run if :meth:`run_forever` is called again later.
-
-.. method:: BaseEventLoop.is_closed()
-
- Returns ``True`` if the event loop was closed.
-
- .. versionadded:: 3.4.2
-
-.. method:: BaseEventLoop.close()
-
- Close the event loop. The loop should not be running.
-
- This clears the queues and shuts down the executor, but does not wait for
- the executor to finish.
-
- The event loop must not be running.
-
- This is idempotent and irreversible. No other methods should be called after
- this one.
-
-
-Calls
------
-
-.. method:: BaseEventLoop.call_soon(callback, \*args)
-
- Arrange for a callback to be called as soon as possible.
-
- This operates as a FIFO queue, callbacks are called in the order in
- which they are registered. Each callback will be called exactly once.
-
- Any positional arguments after the callback will be passed to the
- callback when it is called.
-
- An instance of :class:`asyncio.Handle` is returned.
-
-.. method:: BaseEventLoop.call_soon_threadsafe(callback, \*args)
-
- Like :meth:`call_soon`, but thread safe.
-
-
-.. _asyncio-delayed-calls:
-
-Delayed calls
--------------
-
-The event loop has its own internal clock for computing timeouts.
-Which clock is used depends on the (platform-specific) event loop
-implementation; ideally it is a monotonic clock. This will generally be
-a different clock than :func:`time.time`.
-
-.. note::
-
- Timeouts (relative *delay* or absolute *when*) should not exceed one day.
-
-
-.. method:: BaseEventLoop.call_later(delay, callback, *args)
-
- Arrange for the *callback* to be called after the given *delay*
- seconds (either an int or float).
-
- An instance of :class:`asyncio.Handle` is returned.
-
- *callback* will be called exactly once per call to :meth:`call_later`.
- If two callbacks are scheduled for exactly the same time, it is
- undefined which will be called first.
-
- The optional positional *args* will be passed to the callback when it
- is called. If you want the callback to be called with some named
- arguments, use a closure or :func:`functools.partial`.
-
-.. method:: BaseEventLoop.call_at(when, callback, *args)
-
- Arrange for the *callback* to be called at the given absolute timestamp
- *when* (an int or float), using the same time reference as :meth:`time`.
-
- This method's behavior is the same as :meth:`call_later`.
-
-.. method:: BaseEventLoop.time()
-
- Return the current time, as a :class:`float` value, according to the
- event loop's internal clock.
-
-.. seealso::
-
- The :func:`asyncio.sleep` function.
-
-
-Coroutines
-----------
-
-.. method:: BaseEventLoop.create_task(coro)
-
- Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
- a future. Return a :class:`Task` object.
-
- Third-party event loops can use their own subclass of :class:`Task` for
- interoperability. In this case, the result type is a subclass of
- :class:`Task`.
-
- .. seealso::
-
- The :meth:`async` function.
-
- .. versionadded:: 3.4.2
-
-
-Creating connections
---------------------
-
-.. method:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
-
- Create a streaming transport connection to a given Internet *host* and
- *port*: socket family :py:data:`~socket.AF_INET` or
- :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
- socket type :py:data:`~socket.SOCK_STREAM`. *protocol_factory* must be a
- callable returning a :ref:`protocol <asyncio-protocol>` instance.
-
- This method is a :ref:`coroutine <coroutine>` which will try to
- establish the connection in the background. When successful, the
- coroutine returns a ``(transport, protocol)`` pair.
-
- The chronological synopsis of the underlying operation is as follows:
-
- #. The connection is established, and a :ref:`transport <asyncio-transport>`
- is created to represent it.
-
- #. *protocol_factory* is called without arguments and must return a
- :ref:`protocol <asyncio-protocol>` instance.
-
- #. The protocol instance is tied to the transport, and its
- :meth:`connection_made` method is called.
-
- #. The coroutine returns successfully with the ``(transport, protocol)``
- pair.
-
- The created transport is an implementation-dependent bidirectional stream.
-
- .. note::
- *protocol_factory* can be any kind of callable, not necessarily
- a class. For example, if you want to use a pre-created
- protocol instance, you can pass ``lambda: my_protocol``.
-
- Options allowing to change how the connection is created:
-
- * *ssl*: if given and not false, a SSL/TLS transport is created
- (by default a plain TCP transport is created). If *ssl* is
- a :class:`ssl.SSLContext` object, this context is used to create
- the transport; if *ssl* is :const:`True`, a context with some
- unspecified default settings is used.
-
- .. seealso:: :ref:`SSL/TLS security considerations <ssl-security>`
-
- * *server_hostname*, is only for use together with *ssl*,
- and sets or overrides the hostname that the target server's certificate
- will be matched against. By default the value of the *host* argument
- is used. If *host* is empty, there is no default and you must pass a
- value for *server_hostname*. If *server_hostname* is an empty
- string, hostname matching is disabled (which is a serious security
- risk, allowing for man-in-the-middle-attacks).
-
- * *family*, *proto*, *flags* are the optional address family, protocol
- and flags to be passed through to getaddrinfo() for *host* resolution.
- If given, these should all be integers from the corresponding
- :mod:`socket` module constants.
-
- * *sock*, if given, should be an existing, already connected
- :class:`socket.socket` object to be used by the transport.
- If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*
- and *local_addr* should be specified.
-
- * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
- to bind the socket to locally. The *local_host* and *local_port*
- are looked up using getaddrinfo(), similarly to *host* and *port*.
-
- .. seealso::
-
- The :func:`open_connection` function can be used to get a pair of
- (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.
-
-
-.. method:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
-
- Create datagram connection: socket family :py:data:`~socket.AF_INET` or
- :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
- socket type :py:data:`~socket.SOCK_DGRAM`.
-
- This method is a :ref:`coroutine <coroutine>` which will try to
- establish the connection in the background. When successful, the
- coroutine returns a ``(transport, protocol)`` pair.
-
- See the :meth:`BaseEventLoop.create_connection` method for parameters.
-
-
-.. method:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
-
- Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket
- type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket
- family is used to communicate between processes on the same machine
- efficiently.
-
- This method is a :ref:`coroutine <coroutine>` which will try to
- establish the connection in the background. When successful, the
- coroutine returns a ``(transport, protocol)`` pair.
-
- See the :meth:`BaseEventLoop.create_connection` method for parameters.
-
- Availability: UNIX.
-
-
-Creating listening connections
-------------------------------
-
-.. method:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
-
- Create a TCP server bound to host and port. Return an
- :class:`AbstractServer` object which can be used to stop the service.
-
- This method is a :ref:`coroutine <coroutine>`.
-
- If *host* is an empty string or None all interfaces are assumed
- and a list of multiple sockets will be returned (most likely
- one for IPv4 and another one for IPv6).
-
- *family* can be set to either :data:`~socket.AF_INET` or
- :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6. If not set
- it will be determined from host (defaults to :data:`~socket.AF_UNSPEC`).
-
- *flags* is a bitmask for :meth:`getaddrinfo`.
-
- *sock* can optionally be specified in order to use a preexisting
- socket object.
-
- *backlog* is the maximum number of queued connections passed to
- :meth:`~socket.socket.listen` (defaults to 100).
-
- ssl can be set to an :class:`~ssl.SSLContext` to enable SSL over the
- accepted connections.
-
- *reuse_address* tells the kernel to reuse a local socket in
- TIME_WAIT state, without waiting for its natural timeout to
- expire. If not specified will automatically be set to True on
- UNIX.
-
- .. seealso::
-
- The function :func:`start_server` creates a (:class:`StreamReader`,
- :class:`StreamWriter`) pair and calls back a function with this pair.
-
-
-.. method:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
-
- Similar to :meth:`BaseEventLoop.create_server`, but specific to the
- socket family :py:data:`~socket.AF_UNIX`.
-
- Availability: UNIX.
-
-
-
-Watch file descriptors
-----------------------
-
-.. method:: BaseEventLoop.add_reader(fd, callback, \*args)
-
- Start watching the file descriptor for read availability and then call the
- *callback* with specified arguments.
-
-.. method:: BaseEventLoop.remove_reader(fd)
-
- Stop watching the file descriptor for read availability.
-
-.. method:: BaseEventLoop.add_writer(fd, callback, \*args)
-
- Start watching the file descriptor for write availability and then call the
- *callback* with specified arguments.
-
-.. method:: BaseEventLoop.remove_writer(fd)
-
- Stop watching the file descriptor for write availability.
-
-
-Low-level socket operations
----------------------------
-
-.. method:: BaseEventLoop.sock_recv(sock, nbytes)
-
- Receive data from the socket. The return value is a bytes object
- representing the data received. The maximum amount of data to be received
- at once is specified by *nbytes*.
-
- This method is a :ref:`coroutine <coroutine>`.
-
- .. seealso::
-
- The :meth:`socket.socket.recv` method.
-
-.. method:: BaseEventLoop.sock_sendall(sock, data)
-
- Send data to the socket. The socket must be connected to a remote socket.
- This method continues to send data from *data* until either all data has
- been sent or an error occurs. ``None`` is returned on success. On error,
- an exception is raised, and there is no way to determine how much data, if
- any, was successfully processed by the receiving end of the connection.
-
- This method is a :ref:`coroutine <coroutine>`.
-
- .. seealso::
-
- The :meth:`socket.socket.sendall` method.
-
-.. method:: BaseEventLoop.sock_connect(sock, address)
-
- Connect to a remote socket at *address*.
-
- The *address* must be already resolved to avoid the trap of hanging the
- entire event loop when the address requires doing a DNS lookup. For
- example, it must be an IP address, not an hostname, for
- :py:data:`~socket.AF_INET` and :py:data:`~socket.AF_INET6` address families.
- Use :meth:`getaddrinfo` to resolve the hostname asynchronously.
-
- This method is a :ref:`coroutine <coroutine>`.
-
- .. seealso::
-
- The :meth:`BaseEventLoop.create_connection` method, the
- :func:`open_connection` function and the :meth:`socket.socket.connect`
- method.
-
-
-.. method:: BaseEventLoop.sock_accept(sock)
-
- Accept a connection. The socket must be bound to an address and listening
- for connections. The return value is a pair ``(conn, address)`` where *conn*
- is a *new* socket object usable to send and receive data on the connection,
- and *address* is the address bound to the socket on the other end of the
- connection.
-
- This method is a :ref:`coroutine <coroutine>`.
-
- .. seealso::
-
- The :meth:`BaseEventLoop.create_server` method, the :func:`start_server`
- function and the :meth:`socket.socket.accept` method.
-
-
-Resolve host name
------------------
-
-.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
-
- This method is a :ref:`coroutine <coroutine>`, similar to
- :meth:`socket.getaddrinfo` function but non-blocking.
-
-.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
-
- This method is a :ref:`coroutine <coroutine>`, similar to
- :meth:`socket.getnameinfo` function but non-blocking.
-
-
-Connect pipes
--------------
-
-.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
-
- Register read pipe in eventloop. Set the *pipe* to non-blocking mode.
-
- *protocol_factory* should instantiate object with :class:`Protocol`
- interface. *pipe* is a :term:`file-like object <file object>`.
- Return pair ``(transport, protocol)``, where *transport* supports the
- :class:`ReadTransport` interface.
-
- This method is 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 is a :ref:`coroutine <coroutine>`.
-
-.. seealso::
-
- The :meth:`BaseEventLoop.subprocess_exec` and
- :meth:`BaseEventLoop.subprocess_shell` methods.
-
-
-UNIX signals
-------------
-
-Availability: UNIX only.
-
-.. method:: BaseEventLoop.add_signal_handler(signum, callback, \*args)
-
- Add a handler for a signal.
-
- Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
- Raise :exc:`RuntimeError` if there is a problem setting up the handler.
-
-.. method:: BaseEventLoop.remove_signal_handler(sig)
-
- Remove a handler for a signal.
-
- Return ``True`` if a signal handler was removed, ``False`` if not.
-
-.. seealso::
-
- The :mod:`signal` module.
-
-
-Executor
---------
-
-Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or
-pool of processes). By default, an event loop uses a thread pool executor
-(:class:`~concurrent.futures.ThreadPoolExecutor`).
-
-.. method:: BaseEventLoop.run_in_executor(executor, callback, \*args)
-
- Arrange for a callback to be called in the specified executor.
-
- The *executor* argument should be an :class:`~concurrent.futures.Executor`
- instance. The default executor is used if *executor* is ``None``.
-
- This method is a :ref:`coroutine <coroutine>`.
-
-.. method:: BaseEventLoop.set_default_executor(executor)
-
- Set the default executor used by :meth:`run_in_executor`.
-
-
-Error Handling API
-------------------
-
-Allows to customize how exceptions are handled in the event loop.
-
-.. method:: BaseEventLoop.set_exception_handler(handler)
-
- Set *handler* as the new event loop exception handler.
-
- If *handler* is ``None``, the default exception handler will
- be set.
-
- If *handler* is a callable object, it should have a
- matching signature to ``(loop, context)``, where ``loop``
- will be a reference to the active event loop, ``context``
- will be a ``dict`` object (see :meth:`call_exception_handler`
- documentation for details about context).
-
-.. method:: BaseEventLoop.default_exception_handler(context)
-
- Default exception handler.
-
- This is called when an exception occurs and no exception
- handler is set, and can be called by a custom exception
- handler that wants to defer to the default behavior.
-
- *context* parameter has the same meaning as in
- :meth:`call_exception_handler`.
-
-.. method:: BaseEventLoop.call_exception_handler(context)
-
- Call the current event loop exception handler.
-
- *context* is a ``dict`` object containing the following keys
- (new keys may be introduced later):
-
- * 'message': Error message;
- * 'exception' (optional): Exception object;
- * 'future' (optional): :class:`asyncio.Future` instance;
- * 'handle' (optional): :class:`asyncio.Handle` instance;
- * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
- * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
- * 'socket' (optional): :class:`socket.socket` instance.
-
- .. note::
-
- Note: this method should not be overloaded in subclassed
- event loops. For any custom exception handling, use
- :meth:`set_exception_handler()` method.
-
-Debug mode
-----------
-
-.. method:: BaseEventLoop.get_debug()
-
- Get the debug mode (:class:`bool`) of the event loop.
-
- The default value is ``True`` if the environment variable
- :envvar:`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False``
- otherwise.
-
- .. versionadded:: 3.4.2
-
-.. method:: BaseEventLoop.set_debug(enabled: bool)
-
- Set the debug mode of the event loop.
-
- .. versionadded:: 3.4.2
-
-.. seealso::
-
- The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
-
-
-Server
-------
-
-.. class:: AbstractServer
-
- Abstract server returned by :func:`BaseEventLoop.create_server`.
-
- .. method:: close()
-
- Stop serving. This leaves existing connections open.
-
- .. method:: wait_closed()
-
- A :ref:`coroutine <coroutine>` to wait until service is closed.
-
-
-Handle
-------
-
-.. class:: Handle
-
- A callback wrapper object returned by :func:`BaseEventLoop.call_soon`,
- :func:`BaseEventLoop.call_soon_threadsafe`, :func:`BaseEventLoop.call_later`,
- and :func:`BaseEventLoop.call_at`.
-
- .. method:: cancel()
-
- Cancel the call.
-
-
-.. _asyncio-hello-world-callback:
-
-Example: Hello World (callback)
--------------------------------
-
-Print ``Hello World`` every two seconds, using a callback::
-
- import asyncio
-
- def print_and_repeat(loop):
- print('Hello World')
- loop.call_later(2, print_and_repeat, loop)
-
- loop = asyncio.get_event_loop()
- loop.call_soon(print_and_repeat, loop)
- try:
- loop.run_forever()
- finally:
- loop.close()
-
-.. seealso::
-
- :ref:`Hello World example using a coroutine <asyncio-hello-world-coroutine>`.
-
-
-Example: Set signal handlers for SIGINT and SIGTERM
----------------------------------------------------
-
-Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM`::
-
- import asyncio
- import functools
- import os
- import signal
-
- def ask_exit(signame):
- print("got signal %s: exit" % signame)
- loop.stop()
-
- loop = asyncio.get_event_loop()
- for signame in ('SIGINT', 'SIGTERM'):
- loop.add_signal_handler(getattr(signal, signame),
- functools.partial(ask_exit, signame))
-
- print("Event loop running forever, press CTRL+c to interrupt.")
- print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid())
- try:
- loop.run_forever()
- finally:
- loop.close()
-
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -3,18 +3,18 @@
Subprocess
==========
-Operating system support
-------------------------
+Windows event loop
+------------------
-On Windows, the default event loop uses :class:`selectors.SelectSelector`
-which only supports sockets. The :class:`ProactorEventLoop` should be used to
-support subprocesses. However, the latter does not support SSL.
+On Windows, the default event loop is :class:`SelectorEventLoop` which does not
+support subprocesses. :class:`ProactorEventLoop` should be used instead.
+Example to use it on Windows::
-On Mac OS X older than 10.9 (Mavericks), :class:`selectors.KqueueSelector`
-does not support character devices like PTY, whereas it is used by the
-default event loop. The :class:`SelectorEventLoop` can be used with
-:class:`SelectSelector` or :class:`PollSelector` to handle character
-devices on Mac OS X 10.6 (Snow Leopard) and later.
+ import asyncio, os
+
+ if os.name == 'nt':
+ loop = asyncio.ProactorEventLoop()
+ asyncio.set_event_loop(loop)
Create a subprocess: high-level API using Process
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -45,6 +45,7 @@
:maxdepth: 3
asyncio-eventloop.rst
+ asyncio-eventloops.rst
asyncio-task.rst
asyncio-protocol.rst
asyncio-stream.rst
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list