Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 1 | .. currentmodule:: asyncio |
| 2 | |
| 3 | Event loops |
| 4 | =========== |
| 5 | |
lf | 627d2c8 | 2017-07-25 17:03:51 -0600 | [diff] [blame] | 6 | **Source code:** :source:`Lib/asyncio/events.py` |
| 7 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 8 | Event loop functions |
| 9 | -------------------- |
| 10 | |
| 11 | The following functions are convenient shortcuts to accessing the methods of the |
| 12 | global policy. Note that this provides access to the default policy, unless an |
| 13 | alternative policy was set by calling :func:`set_event_loop_policy` earlier in |
| 14 | the execution of the process. |
| 15 | |
| 16 | .. function:: get_event_loop() |
| 17 | |
| 18 | Equivalent to calling ``get_event_loop_policy().get_event_loop()``. |
| 19 | |
| 20 | .. function:: set_event_loop(loop) |
| 21 | |
| 22 | Equivalent to calling ``get_event_loop_policy().set_event_loop(loop)``. |
| 23 | |
| 24 | .. function:: new_event_loop() |
| 25 | |
| 26 | Equivalent to calling ``get_event_loop_policy().new_event_loop()``. |
| 27 | |
Yury Selivanov | abae67e | 2017-12-11 10:07:44 -0500 | [diff] [blame] | 28 | .. function:: get_running_loop() |
| 29 | |
| 30 | Return the running event loop in the current OS thread. If there |
| 31 | is no running event loop a :exc:`RuntimeError` is raised. |
| 32 | |
| 33 | .. versionadded:: 3.7 |
| 34 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 35 | |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 36 | .. _asyncio-event-loops: |
| 37 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 38 | Available event loops |
| 39 | --------------------- |
| 40 | |
| 41 | asyncio currently provides two implementations of event loops: |
| 42 | :class:`SelectorEventLoop` and :class:`ProactorEventLoop`. |
| 43 | |
| 44 | .. class:: SelectorEventLoop |
| 45 | |
| 46 | Event loop based on the :mod:`selectors` module. Subclass of |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 47 | :class:`AbstractEventLoop`. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 48 | |
| 49 | Use the most efficient selector available on the platform. |
| 50 | |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 51 | On Windows, only sockets are supported (ex: pipes are not supported): |
| 52 | see the `MSDN documentation of select |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 53 | <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_. |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 54 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 55 | .. class:: ProactorEventLoop |
| 56 | |
| 57 | Proactor event loop for Windows using "I/O Completion Ports" aka IOCP. |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 58 | Subclass of :class:`AbstractEventLoop`. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 59 | |
| 60 | Availability: Windows. |
| 61 | |
| 62 | .. seealso:: |
| 63 | |
| 64 | `MSDN documentation on I/O Completion Ports |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 65 | <https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198%28v=vs.85%29.aspx>`_. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 66 | |
| 67 | Example to use a :class:`ProactorEventLoop` on Windows:: |
| 68 | |
Guido van Rossum | 8778c6b | 2015-11-02 09:15:47 -0800 | [diff] [blame] | 69 | import asyncio, sys |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 70 | |
Guido van Rossum | 8778c6b | 2015-11-02 09:15:47 -0800 | [diff] [blame] | 71 | if sys.platform == 'win32': |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 72 | loop = asyncio.ProactorEventLoop() |
| 73 | asyncio.set_event_loop(loop) |
| 74 | |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 75 | .. _asyncio-platform-support: |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 76 | |
| 77 | Platform support |
| 78 | ---------------- |
| 79 | |
| 80 | The :mod:`asyncio` module has been designed to be portable, but each platform |
| 81 | still has subtle differences and may not support all :mod:`asyncio` features. |
| 82 | |
| 83 | Windows |
| 84 | ^^^^^^^ |
| 85 | |
| 86 | Common limits of Windows event loops: |
| 87 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 88 | - :meth:`~AbstractEventLoop.create_unix_connection` and |
| 89 | :meth:`~AbstractEventLoop.create_unix_server` are not supported: the socket |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 90 | family :data:`socket.AF_UNIX` is specific to UNIX |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 91 | - :meth:`~AbstractEventLoop.add_signal_handler` and |
| 92 | :meth:`~AbstractEventLoop.remove_signal_handler` are not supported |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 93 | - :meth:`EventLoopPolicy.set_child_watcher` is not supported. |
| 94 | :class:`ProactorEventLoop` supports subprocesses. It has only one |
| 95 | implementation to watch child processes, there is no need to configure it. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 96 | |
| 97 | :class:`SelectorEventLoop` specific limits: |
| 98 | |
Victor Stinner | 7eb1031 | 2015-01-09 15:59:44 +0100 | [diff] [blame] | 99 | - :class:`~selectors.SelectSelector` is used which only supports sockets |
| 100 | and is limited to 512 sockets. |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 101 | - :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` only |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 102 | accept file descriptors of sockets |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 103 | - Pipes are not supported |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 104 | (ex: :meth:`~AbstractEventLoop.connect_read_pipe`, |
| 105 | :meth:`~AbstractEventLoop.connect_write_pipe`) |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 106 | - :ref:`Subprocesses <asyncio-subprocess>` are not supported |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 107 | (ex: :meth:`~AbstractEventLoop.subprocess_exec`, |
| 108 | :meth:`~AbstractEventLoop.subprocess_shell`) |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 109 | |
| 110 | :class:`ProactorEventLoop` specific limits: |
| 111 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 112 | - :meth:`~AbstractEventLoop.create_datagram_endpoint` (UDP) is not supported |
| 113 | - :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` are |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 114 | not supported |
| 115 | |
| 116 | The resolution of the monotonic clock on Windows is usually around 15.6 msec. |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 117 | The best resolution is 0.5 msec. The resolution depends on the hardware |
| 118 | (availability of `HPET |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 119 | <https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the Windows |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 120 | configuration. See :ref:`asyncio delayed calls <asyncio-delayed-calls>`. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 121 | |
Victor Stinner | 4ec0422 | 2015-01-14 00:30:22 +0100 | [diff] [blame] | 122 | .. versionchanged:: 3.5 |
| 123 | |
| 124 | :class:`ProactorEventLoop` now supports SSL. |
| 125 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 126 | |
| 127 | Mac OS X |
| 128 | ^^^^^^^^ |
| 129 | |
| 130 | Character devices like PTY are only well supported since Mavericks (Mac OS |
| 131 | 10.9). They are not supported at all on Mac OS 10.5 and older. |
| 132 | |
| 133 | On Mac OS 10.6, 10.7 and 10.8, the default event loop is |
| 134 | :class:`SelectorEventLoop` which uses :class:`selectors.KqueueSelector`. |
| 135 | :class:`selectors.KqueueSelector` does not support character devices on these |
| 136 | versions. The :class:`SelectorEventLoop` can be used with |
| 137 | :class:`~selectors.SelectSelector` or :class:`~selectors.PollSelector` to |
| 138 | support character devices on these versions of Mac OS X. Example:: |
| 139 | |
| 140 | import asyncio |
| 141 | import selectors |
| 142 | |
| 143 | selector = selectors.SelectSelector() |
| 144 | loop = asyncio.SelectorEventLoop(selector) |
| 145 | asyncio.set_event_loop(loop) |
| 146 | |
| 147 | |
| 148 | Event loop policies and the default policy |
| 149 | ------------------------------------------ |
| 150 | |
| 151 | Event loop management is abstracted with a *policy* pattern, to provide maximal |
| 152 | flexibility for custom platforms and frameworks. Throughout the execution of a |
| 153 | process, a single global policy object manages the event loops available to the |
| 154 | process based on the calling context. A policy is an object implementing the |
| 155 | :class:`AbstractEventLoopPolicy` interface. |
| 156 | |
| 157 | For most users of :mod:`asyncio`, policies never have to be dealt with |
Antoine Pitrou | 4135c89 | 2017-11-07 10:26:32 +0100 | [diff] [blame] | 158 | explicitly, since the default global policy is sufficient (see below). |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 159 | |
Antoine Pitrou | 4135c89 | 2017-11-07 10:26:32 +0100 | [diff] [blame] | 160 | The module-level functions |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 161 | :func:`get_event_loop` and :func:`set_event_loop` provide convenient access to |
| 162 | event loops managed by the default policy. |
| 163 | |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 164 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 165 | Event loop policy interface |
| 166 | --------------------------- |
| 167 | |
| 168 | An event loop policy must implement the following interface: |
| 169 | |
| 170 | .. class:: AbstractEventLoopPolicy |
| 171 | |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 172 | Event loop policy. |
| 173 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 174 | .. method:: get_event_loop() |
| 175 | |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 176 | Get the event loop for the current context. |
| 177 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 178 | Returns an event loop object implementing the :class:`AbstractEventLoop` |
Mandeep Singh | e55de2d | 2018-05-30 00:07:08 +0530 | [diff] [blame] | 179 | interface. In case called from coroutine, it returns the currently |
| 180 | running event loop. |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 181 | |
| 182 | Raises an exception in case no event loop has been set for the current |
| 183 | context and the current policy does not specify to create one. It must |
| 184 | never return ``None``. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 185 | |
Mandeep Singh | e55de2d | 2018-05-30 00:07:08 +0530 | [diff] [blame] | 186 | .. versionchanged:: 3.6 |
| 187 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 188 | .. method:: set_event_loop(loop) |
| 189 | |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 190 | Set the event loop for the current context to *loop*. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 191 | |
| 192 | .. method:: new_event_loop() |
| 193 | |
Victor Stinner | 1deee54 | 2014-11-28 13:58:28 +0100 | [diff] [blame] | 194 | Create and return a new event loop object according to this policy's |
| 195 | rules. |
| 196 | |
| 197 | If there's need to set this loop as the event loop for the current |
| 198 | context, :meth:`set_event_loop` must be called explicitly. |
| 199 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 200 | |
Antoine Pitrou | 4135c89 | 2017-11-07 10:26:32 +0100 | [diff] [blame] | 201 | The default policy defines context as the current thread, and manages an event |
Pablo Galindo | 77106b2 | 2017-12-10 17:34:59 +0000 | [diff] [blame] | 202 | loop per thread that interacts with :mod:`asyncio`. An exception to this rule |
| 203 | happens when :meth:`~AbstractEventLoopPolicy.get_event_loop` is called from a |
| 204 | running future/coroutine, in which case it will return the current loop |
| 205 | running that future/coroutine. |
| 206 | |
| 207 | If the current thread doesn't already have an event loop associated with it, |
| 208 | the default policy's :meth:`~AbstractEventLoopPolicy.get_event_loop` method |
| 209 | creates one when called from the main thread, but raises :exc:`RuntimeError` |
| 210 | otherwise. |
Antoine Pitrou | 4135c89 | 2017-11-07 10:26:32 +0100 | [diff] [blame] | 211 | |
| 212 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 213 | Access to the global loop policy |
| 214 | -------------------------------- |
| 215 | |
| 216 | .. function:: get_event_loop_policy() |
| 217 | |
| 218 | Get the current event loop policy. |
| 219 | |
| 220 | .. function:: set_event_loop_policy(policy) |
| 221 | |
| 222 | Set the current event loop policy. If *policy* is ``None``, the default |
| 223 | policy is restored. |
Antoine Pitrou | 4135c89 | 2017-11-07 10:26:32 +0100 | [diff] [blame] | 224 | |
| 225 | |
| 226 | Customizing the event loop policy |
| 227 | --------------------------------- |
| 228 | |
| 229 | To implement a new event loop policy, it is recommended you subclass the |
| 230 | concrete default event loop policy :class:`DefaultEventLoopPolicy` |
| 231 | and override the methods for which you want to change behavior, for example:: |
| 232 | |
| 233 | class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy): |
| 234 | |
| 235 | def get_event_loop(self): |
| 236 | """Get the event loop. |
| 237 | |
| 238 | This may be None or an instance of EventLoop. |
| 239 | """ |
| 240 | loop = super().get_event_loop() |
| 241 | # Do something with loop ... |
| 242 | return loop |
| 243 | |
| 244 | asyncio.set_event_loop_policy(MyEventLoopPolicy()) |