diff options
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 82 | ||||
| -rw-r--r-- | Doc/library/asyncio-eventloops.rst | 176 | ||||
| -rw-r--r-- | Doc/library/asyncio-subprocess.rst | 24 | ||||
| -rw-r--r-- | Doc/library/asyncio.rst | 1 |
4 files changed, 195 insertions, 88 deletions
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 1a80921..c82ea48 100644 --- 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 @@ It provides multiple facilities, amongst which: * 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 @@ Creating listening connections Availability: UNIX. - Watch file descriptors ---------------------- @@ -624,7 +554,6 @@ Debug mode The :ref:`debug mode of asyncio <asyncio-debug-mode>`. - Server ------ @@ -652,7 +581,8 @@ Handle .. method:: cancel() - Cancel the call. + Cancel the call. + .. _asyncio-hello-world-callback: diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst new file mode 100644 index 0000000..b530d3c --- /dev/null +++ b/Doc/library/asyncio-eventloops.rst @@ -0,0 +1,176 @@ +.. currentmodule:: asyncio + +Event loops +=========== + +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()``. + + +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 +--------------------------- + +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. + diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 3f57a82..3386bf5 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -3,18 +3,18 @@ Subprocess ========== -Operating system support ------------------------- - -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 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. +Windows event loop +------------------ + +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:: + + 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 index 23731b1..9857c93 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -45,6 +45,7 @@ Table of content: :maxdepth: 3 asyncio-eventloop.rst + asyncio-eventloops.rst asyncio-task.rst asyncio-protocol.rst asyncio-stream.rst |