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