Skip to content

Commit aea8229

Browse files
vstinnervstinner
committed
Issue #21680: Document asyncio event loops
1 parent 530ef2f commit aea8229

File tree

4 files changed

+195
-88
lines changed

4 files changed

+195
-88
lines changed

‎Doc/library/asyncio-eventloop.rst

+6-76
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
.. _asyncio-event-loop:
44

5-
Event loops
6-
===========
5+
Base Event Loop
6+
===============
77

88
The event loop is the central execution device provided by :mod:`asyncio`.
99
It provides multiple facilities, amongst which:
@@ -18,78 +18,9 @@ It provides multiple facilities, amongst which:
1818

1919
* Delegating costly function calls to a pool of threads.
2020

21-
Event loop policies and the default policy
22-
------------------------------------------
21+
.. class:: BaseEventLoop
2322

24-
Event loop management is abstracted with a *policy* pattern, to provide maximal
25-
flexibility for custom platforms and frameworks. Throughout the execution of a
26-
process, a single global policy object manages the event loops available to the
27-
process based on the calling context. A policy is an object implementing the
28-
:class:`AbstractEventLoopPolicy` interface.
29-
30-
For most users of :mod:`asyncio`, policies never have to be dealt with
31-
explicitly, since the default global policy is sufficient.
32-
33-
The default policy defines context as the current thread, and manages an event
34-
loop per thread that interacts with :mod:`asyncio`. The module-level functions
35-
:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
36-
event loops managed by the default policy.
37-
38-
Event loop functions
39-
--------------------
40-
41-
The following functions are convenient shortcuts to accessing the methods of the
42-
global policy. Note that this provides access to the default policy, unless an
43-
alternative policy was set by calling :func:`set_event_loop_policy` earlier in
44-
the execution of the process.
45-
46-
.. function:: get_event_loop()
47-
48-
Equivalent to calling ``get_event_loop_policy().get_event_loop()``.
49-
50-
.. function:: set_event_loop(loop)
51-
52-
Equivalent to calling ``get_event_loop_policy().set_event_loop(loop)``.
53-
54-
.. function:: new_event_loop()
55-
56-
Equivalent to calling ``get_event_loop_policy().new_event_loop()``.
57-
58-
Event loop policy interface
59-
---------------------------
60-
61-
An event loop policy must implement the following interface:
62-
63-
.. class:: AbstractEventLoopPolicy
64-
65-
.. method:: get_event_loop()
66-
67-
Get the event loop for the current context. Returns an event loop object
68-
implementing the :class:`BaseEventLoop` interface, or raises an exception in case
69-
no event loop has been set for the current context and the current policy
70-
does not specify to create one. It should never return ``None``.
71-
72-
.. method:: set_event_loop(loop)
73-
74-
Set the event loop for the current context to *loop*.
75-
76-
.. method:: new_event_loop()
77-
78-
Create and return a new event loop object according to this policy's rules.
79-
If there's need to set this loop as the event loop for the current context,
80-
:meth:`set_event_loop` must be called explicitly.
81-
82-
Access to the global loop policy
83-
--------------------------------
84-
85-
.. function:: get_event_loop_policy()
86-
87-
Get the current event loop policy.
88-
89-
.. function:: set_event_loop_policy(policy)
90-
91-
Set the current event loop policy. If *policy* is ``None``, the default
92-
policy is restored.
23+
Base class of event loops.
9324

9425
Run an event loop
9526
-----------------
@@ -375,7 +306,6 @@ Creating listening connections
375306
Availability: UNIX.
376307

377308

378-
379309
Watch file descriptors
380310
----------------------
381311

@@ -624,7 +554,6 @@ Debug mode
624554

625555
The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
626556

627-
628557
Server
629558
------
630559

@@ -652,7 +581,8 @@ Handle
652581

653582
.. method:: cancel()
654583

655-
Cancel the call.
584+
Cancel the call.
585+
656586

657587

658588
.. _asyncio-hello-world-callback:

‎Doc/library/asyncio-eventloops.rst

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
.. currentmodule:: asyncio
2+
3+
Event loops
4+
===========
5+
6+
Event loop functions
7+
--------------------
8+
9+
The following functions are convenient shortcuts to accessing the methods of the
10+
global policy. Note that this provides access to the default policy, unless an
11+
alternative policy was set by calling :func:`set_event_loop_policy` earlier in
12+
the execution of the process.
13+
14+
.. function:: get_event_loop()
15+
16+
Equivalent to calling ``get_event_loop_policy().get_event_loop()``.
17+
18+
.. function:: set_event_loop(loop)
19+
20+
Equivalent to calling ``get_event_loop_policy().set_event_loop(loop)``.
21+
22+
.. function:: new_event_loop()
23+
24+
Equivalent to calling ``get_event_loop_policy().new_event_loop()``.
25+
26+
27+
Available event loops
28+
---------------------
29+
30+
asyncio currently provides two implementations of event loops:
31+
:class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
32+
33+
.. class:: SelectorEventLoop
34+
35+
Event loop based on the :mod:`selectors` module. Subclass of
36+
:class:`BaseEventLoop`.
37+
38+
Use the most efficient selector available on the platform.
39+
40+
.. class:: ProactorEventLoop
41+
42+
Proactor event loop for Windows using "I/O Completion Ports" aka IOCP.
43+
Subclass of :class:`BaseEventLoop`.
44+
45+
Availability: Windows.
46+
47+
.. seealso::
48+
49+
`MSDN documentation on I/O Completion Ports
50+
<http://msdn.microsoft.com/en-us/library/windows/desktop/aa365198%28v=vs.85%29.aspx>`_.
51+
52+
Example to use a :class:`ProactorEventLoop` on Windows::
53+
54+
import asyncio, os
55+
56+
if os.name == 'nt':
57+
loop = asyncio.ProactorEventLoop()
58+
asyncio.set_event_loop(loop)
59+
60+
61+
Platform support
62+
----------------
63+
64+
The :mod:`asyncio` module has been designed to be portable, but each platform
65+
still has subtle differences and may not support all :mod:`asyncio` features.
66+
67+
Windows
68+
^^^^^^^
69+
70+
Common limits of Windows event loops:
71+
72+
- :meth:`~BaseEventLoop.create_unix_server` and
73+
:meth:`~BaseEventLoop.create_unix_server` are not supported: specific to UNIX
74+
- :meth:`~BaseEventLoop.add_signal_handler` and
75+
:meth:`~BaseEventLoop.remove_signal_handler` are not supported
76+
- Pipes are not supported: :meth:`~BaseEventLoop.connect_read_pipe` and
77+
:meth:`~BaseEventLoop.connect_write_pipe`
78+
- :meth:`EventLoopPolicy.set_child_watcher` is not supported
79+
80+
:class:`SelectorEventLoop` specific limits:
81+
82+
- :class:`~selectors.SelectSelector` is used but it only supports sockets,
83+
see the `MSDN documentation of select
84+
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_.
85+
- it is not possible to execute subprocesses
86+
- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` only
87+
accept file descriptors of sockets
88+
89+
:class:`ProactorEventLoop` specific limits:
90+
91+
- SSL is not supported: :meth:`~BaseEventLoop.create_connection` and
92+
:meth:`~BaseEventLoop.create_server` cannot be used with SSL for example
93+
- :meth:`~BaseEventLoop.create_datagram_endpoint` (UDP) is not supported
94+
- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` are
95+
not supported
96+
97+
The resolution of the monotonic clock on Windows is usually around 15.6 msec.
98+
The best resolution is 0.5 msec. The exact resolution depends on the hardware
99+
(availability of HPET) and the Windows configuration. See :ref:`asyncio delayed
100+
calls <asyncio-delayed-calls>`.
101+
102+
103+
Mac OS X
104+
^^^^^^^^
105+
106+
Character devices like PTY are only well supported since Mavericks (Mac OS
107+
10.9). They are not supported at all on Mac OS 10.5 and older.
108+
109+
On Mac OS 10.6, 10.7 and 10.8, the default event loop is
110+
:class:`SelectorEventLoop` which uses :class:`selectors.KqueueSelector`.
111+
:class:`selectors.KqueueSelector` does not support character devices on these
112+
versions. The :class:`SelectorEventLoop` can be used with
113+
:class:`~selectors.SelectSelector` or :class:`~selectors.PollSelector` to
114+
support character devices on these versions of Mac OS X. Example::
115+
116+
import asyncio
117+
import selectors
118+
119+
selector = selectors.SelectSelector()
120+
loop = asyncio.SelectorEventLoop(selector)
121+
asyncio.set_event_loop(loop)
122+
123+
124+
Event loop policies and the default policy
125+
------------------------------------------
126+
127+
Event loop management is abstracted with a *policy* pattern, to provide maximal
128+
flexibility for custom platforms and frameworks. Throughout the execution of a
129+
process, a single global policy object manages the event loops available to the
130+
process based on the calling context. A policy is an object implementing the
131+
:class:`AbstractEventLoopPolicy` interface.
132+
133+
For most users of :mod:`asyncio`, policies never have to be dealt with
134+
explicitly, since the default global policy is sufficient.
135+
136+
The default policy defines context as the current thread, and manages an event
137+
loop per thread that interacts with :mod:`asyncio`. The module-level functions
138+
:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
139+
event loops managed by the default policy.
140+
141+
Event loop policy interface
142+
---------------------------
143+
144+
An event loop policy must implement the following interface:
145+
146+
.. class:: AbstractEventLoopPolicy
147+
148+
.. method:: get_event_loop()
149+
150+
Get the event loop for the current context. Returns an event loop object
151+
implementing the :class:`BaseEventLoop` interface, or raises an exception in case
152+
no event loop has been set for the current context and the current policy
153+
does not specify to create one. It should never return ``None``.
154+
155+
.. method:: set_event_loop(loop)
156+
157+
Set the event loop for the current context to *loop*.
158+
159+
.. method:: new_event_loop()
160+
161+
Create and return a new event loop object according to this policy's rules.
162+
If there's need to set this loop as the event loop for the current context,
163+
:meth:`set_event_loop` must be called explicitly.
164+
165+
Access to the global loop policy
166+
--------------------------------
167+
168+
.. function:: get_event_loop_policy()
169+
170+
Get the current event loop policy.
171+
172+
.. function:: set_event_loop_policy(policy)
173+
174+
Set the current event loop policy. If *policy* is ``None``, the default
175+
policy is restored.
176+

‎Doc/library/asyncio-subprocess.rst

+12-12
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,18 @@
33
Subprocess
44
==========
55

6-
Operating system support
7-
------------------------
8-
9-
On Windows, the default event loop uses :class:`selectors.SelectSelector`
10-
which only supports sockets. The :class:`ProactorEventLoop` should be used to
11-
support subprocesses. However, the latter does not support SSL.
12-
13-
On Mac OS X older than 10.9 (Mavericks), :class:`selectors.KqueueSelector`
14-
does not support character devices like PTY, whereas it is used by the
15-
default event loop. The :class:`SelectorEventLoop` can be used with
16-
:class:`SelectSelector` or :class:`PollSelector` to handle character
17-
devices on Mac OS X 10.6 (Snow Leopard) and later.
6+
Windows event loop
7+
------------------
8+
9+
On Windows, the default event loop is :class:`SelectorEventLoop` which does not
10+
support subprocesses. :class:`ProactorEventLoop` should be used instead.
11+
Example to use it on Windows::
12+
13+
import asyncio, os
14+
15+
if os.name == 'nt':
16+
loop = asyncio.ProactorEventLoop()
17+
asyncio.set_event_loop(loop)
1818

1919

2020
Create a subprocess: high-level API using Process

‎Doc/library/asyncio.rst

+1
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ Table of content:
4545
:maxdepth: 3
4646

4747
asyncio-eventloop.rst
48+
asyncio-eventloops.rst
4849
asyncio-task.rst
4950
asyncio-protocol.rst
5051
asyncio-stream.rst

0 commit comments

Comments
 (0)