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