R David Murray | 6a14381 | 2013-12-20 14:37:39 -0500 | [diff] [blame] | 1 | .. currentmodule:: asyncio |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 2 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 3 | .. _asyncio-event-loop: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 4 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 5 | Base Event Loop |
| 6 | =============== |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 7 | |
lf | 627d2c8 | 2017-07-25 17:03:51 -0600 | [diff] [blame] | 8 | **Source code:** :source:`Lib/asyncio/events.py` |
| 9 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 10 | The event loop is the central execution device provided by :mod:`asyncio`. |
Zachary Ware | 5e580da | 2015-08-27 15:54:39 -0500 | [diff] [blame] | 11 | It provides multiple facilities, including: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 12 | |
Eli Bendersky | b73c833 | 2014-02-09 06:07:47 -0800 | [diff] [blame] | 13 | * Registering, executing and cancelling delayed calls (timeouts). |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 14 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 15 | * Creating client and server :ref:`transports <asyncio-transport>` for various |
Eli Bendersky | b73c833 | 2014-02-09 06:07:47 -0800 | [diff] [blame] | 16 | kinds of communication. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 17 | |
Eli Bendersky | 136fea2 | 2014-02-09 06:55:58 -0800 | [diff] [blame] | 18 | * Launching subprocesses and the associated :ref:`transports |
| 19 | <asyncio-transport>` for communication with an external program. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 20 | |
Eli Bendersky | b73c833 | 2014-02-09 06:07:47 -0800 | [diff] [blame] | 21 | * Delegating costly function calls to a pool of threads. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 22 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 23 | .. class:: BaseEventLoop |
Eli Bendersky | 136fea2 | 2014-02-09 06:55:58 -0800 | [diff] [blame] | 24 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 25 | This class is an implementation detail. It is a subclass of |
| 26 | :class:`AbstractEventLoop` and may be a base class of concrete |
| 27 | event loop implementations found in :mod:`asyncio`. It should not |
| 28 | be used directly; use :class:`AbstractEventLoop` instead. |
| 29 | ``BaseEventLoop`` should not be subclassed by third-party code; the |
| 30 | internal interface is not stable. |
| 31 | |
| 32 | .. class:: AbstractEventLoop |
| 33 | |
| 34 | Abstract base class of event loops. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 35 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 36 | This class is :ref:`not thread safe <asyncio-multithreading>`. |
| 37 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 38 | Run an event loop |
| 39 | ----------------- |
| 40 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 41 | .. method:: AbstractEventLoop.run_forever() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 42 | |
Guido van Rossum | 41f69f4 | 2015-11-19 13:28:47 -0800 | [diff] [blame] | 43 | Run until :meth:`stop` is called. If :meth:`stop` is called before |
| 44 | :meth:`run_forever()` is called, this polls the I/O selector once |
| 45 | with a timeout of zero, runs all callbacks scheduled in response to |
| 46 | I/O events (and those that were already scheduled), and then exits. |
| 47 | If :meth:`stop` is called while :meth:`run_forever` is running, |
| 48 | this will run the current batch of callbacks and then exit. Note |
| 49 | that callbacks scheduled by callbacks will not run in that case; |
| 50 | they will run the next time :meth:`run_forever` is called. |
| 51 | |
Guido van Rossum | 82f9fea | 2015-11-19 13:33:34 -0800 | [diff] [blame] | 52 | .. versionchanged:: 3.5.1 |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 53 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 54 | .. method:: AbstractEventLoop.run_until_complete(future) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 55 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 56 | Run until the :class:`Future` is done. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 57 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 58 | If the argument is a :ref:`coroutine object <coroutine>`, it is wrapped by |
Yury Selivanov | 04356e1 | 2015-06-30 22:13:22 -0400 | [diff] [blame] | 59 | :func:`ensure_future`. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 60 | |
| 61 | Return the Future's result, or raise its exception. |
| 62 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 63 | .. method:: AbstractEventLoop.is_running() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 64 | |
| 65 | Returns running status of event loop. |
| 66 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 67 | .. method:: AbstractEventLoop.stop() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 68 | |
| 69 | Stop running the event loop. |
| 70 | |
Guido van Rossum | 41f69f4 | 2015-11-19 13:28:47 -0800 | [diff] [blame] | 71 | This causes :meth:`run_forever` to exit at the next suitable |
| 72 | opportunity (see there for more details). |
| 73 | |
Guido van Rossum | 82f9fea | 2015-11-19 13:33:34 -0800 | [diff] [blame] | 74 | .. versionchanged:: 3.5.1 |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 75 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 76 | .. method:: AbstractEventLoop.is_closed() |
Victor Stinner | bb2fc5b | 2014-06-10 10:23:10 +0200 | [diff] [blame] | 77 | |
| 78 | Returns ``True`` if the event loop was closed. |
| 79 | |
| 80 | .. versionadded:: 3.4.2 |
| 81 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 82 | .. method:: AbstractEventLoop.close() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 83 | |
Guido van Rossum | 41f69f4 | 2015-11-19 13:28:47 -0800 | [diff] [blame] | 84 | Close the event loop. The loop must not be running. Pending |
| 85 | callbacks will be lost. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 86 | |
| 87 | This clears the queues and shuts down the executor, but does not wait for |
| 88 | the executor to finish. |
| 89 | |
| 90 | This is idempotent and irreversible. No other methods should be called after |
| 91 | this one. |
| 92 | |
Yury Selivanov | 0366004 | 2016-12-15 17:36:05 -0500 | [diff] [blame] | 93 | |
| 94 | .. coroutinemethod:: AbstractEventLoop.shutdown_asyncgens() |
| 95 | |
| 96 | Schedule all currently open :term:`asynchronous generator` objects to |
| 97 | close with an :meth:`~agen.aclose()` call. After calling this method, |
| 98 | the event loop will issue a warning whenever a new asynchronous generator |
| 99 | is iterated. Should be used to finalize all scheduled asynchronous |
| 100 | generators reliably. Example:: |
| 101 | |
| 102 | try: |
| 103 | loop.run_forever() |
| 104 | finally: |
| 105 | loop.run_until_complete(loop.shutdown_asyncgens()) |
| 106 | loop.close() |
| 107 | |
| 108 | .. versionadded:: 3.6 |
| 109 | |
| 110 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 111 | .. _asyncio-pass-keywords: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 112 | |
| 113 | Calls |
| 114 | ----- |
| 115 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 116 | Most :mod:`asyncio` functions don't accept keywords. If you want to pass |
| 117 | keywords to your callback, use :func:`functools.partial`. For example, |
| 118 | ``loop.call_soon(functools.partial(print, "Hello", flush=True))`` will call |
| 119 | ``print("Hello", flush=True)``. |
| 120 | |
| 121 | .. note:: |
| 122 | :func:`functools.partial` is better than ``lambda`` functions, because |
| 123 | :mod:`asyncio` can inspect :func:`functools.partial` object to display |
| 124 | parameters in debug mode, whereas ``lambda`` functions have a poor |
| 125 | representation. |
| 126 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 127 | .. method:: AbstractEventLoop.call_soon(callback, *args, context=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 128 | |
Victor Stinner | 4d5115c | 2014-12-15 17:50:55 +0100 | [diff] [blame] | 129 | Arrange for a callback to be called as soon as possible. The callback is |
| 130 | called after :meth:`call_soon` returns, when control returns to the event |
| 131 | loop. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 132 | |
Serhiy Storchaka | 4ecfa45 | 2016-05-16 09:31:54 +0300 | [diff] [blame] | 133 | This operates as a :abbr:`FIFO (first-in, first-out)` queue, callbacks |
| 134 | are called in the order in which they are registered. Each callback |
| 135 | will be called exactly once. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 136 | |
| 137 | Any positional arguments after the callback will be passed to the |
| 138 | callback when it is called. |
| 139 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 140 | An optional keyword-only *context* argument allows specifying a custom |
| 141 | :class:`contextvars.Context` for the *callback* to run in. The current |
| 142 | context is used when no *context* is provided. |
| 143 | |
Yury Selivanov | 1096f76 | 2015-06-25 13:49:52 -0400 | [diff] [blame] | 144 | An instance of :class:`asyncio.Handle` is returned, which can be |
| 145 | used to cancel the callback. |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 146 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 147 | :ref:`Use functools.partial to pass keywords to the callback |
| 148 | <asyncio-pass-keywords>`. |
| 149 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 150 | .. versionchanged:: 3.7 |
| 151 | The *context* keyword-only parameter was added. See :pep:`567` |
| 152 | for more details. |
| 153 | |
| 154 | .. method:: AbstractEventLoop.call_soon_threadsafe(callback, *args, context=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 155 | |
| 156 | Like :meth:`call_soon`, but thread safe. |
| 157 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 158 | See the :ref:`concurrency and multithreading <asyncio-multithreading>` |
| 159 | section of the documentation. |
| 160 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 161 | .. versionchanged:: 3.7 |
| 162 | The *context* keyword-only parameter was added. See :pep:`567` |
| 163 | for more details. |
| 164 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 165 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 166 | .. _asyncio-delayed-calls: |
| 167 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 168 | Delayed calls |
| 169 | ------------- |
| 170 | |
| 171 | The event loop has its own internal clock for computing timeouts. |
| 172 | Which clock is used depends on the (platform-specific) event loop |
| 173 | implementation; ideally it is a monotonic clock. This will generally be |
| 174 | a different clock than :func:`time.time`. |
| 175 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 176 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 177 | .. method:: AbstractEventLoop.call_later(delay, callback, *args, context=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 178 | |
| 179 | Arrange for the *callback* to be called after the given *delay* |
| 180 | seconds (either an int or float). |
| 181 | |
Andrew Svetlov | 3d4dbd8 | 2018-02-01 19:59:32 +0200 | [diff] [blame] | 182 | An instance of :class:`asyncio.TimerHandle` is returned, which can be |
Yury Selivanov | 1096f76 | 2015-06-25 13:49:52 -0400 | [diff] [blame] | 183 | used to cancel the callback. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 184 | |
| 185 | *callback* will be called exactly once per call to :meth:`call_later`. |
| 186 | If two callbacks are scheduled for exactly the same time, it is |
| 187 | undefined which will be called first. |
| 188 | |
| 189 | The optional positional *args* will be passed to the callback when it |
| 190 | is called. If you want the callback to be called with some named |
| 191 | arguments, use a closure or :func:`functools.partial`. |
| 192 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 193 | An optional keyword-only *context* argument allows specifying a custom |
| 194 | :class:`contextvars.Context` for the *callback* to run in. The current |
| 195 | context is used when no *context* is provided. |
| 196 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 197 | :ref:`Use functools.partial to pass keywords to the callback |
| 198 | <asyncio-pass-keywords>`. |
| 199 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 200 | .. versionchanged:: 3.7 |
| 201 | The *context* keyword-only parameter was added. See :pep:`567` |
| 202 | for more details. |
| 203 | |
| 204 | .. method:: AbstractEventLoop.call_at(when, callback, *args, context=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 205 | |
| 206 | Arrange for the *callback* to be called at the given absolute timestamp |
Berker Peksag | b556399 | 2014-11-07 19:51:07 +0200 | [diff] [blame] | 207 | *when* (an int or float), using the same time reference as |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 208 | :meth:`AbstractEventLoop.time`. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 209 | |
| 210 | This method's behavior is the same as :meth:`call_later`. |
| 211 | |
Andrew Svetlov | 3d4dbd8 | 2018-02-01 19:59:32 +0200 | [diff] [blame] | 212 | An instance of :class:`asyncio.TimerHandle` is returned, which can be |
Yury Selivanov | 1096f76 | 2015-06-25 13:49:52 -0400 | [diff] [blame] | 213 | used to cancel the callback. |
| 214 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 215 | :ref:`Use functools.partial to pass keywords to the callback |
| 216 | <asyncio-pass-keywords>`. |
| 217 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 218 | .. versionchanged:: 3.7 |
| 219 | The *context* keyword-only parameter was added. See :pep:`567` |
| 220 | for more details. |
| 221 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 222 | .. method:: AbstractEventLoop.time() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 223 | |
| 224 | Return the current time, as a :class:`float` value, according to the |
| 225 | event loop's internal clock. |
| 226 | |
Victor Stinner | 3e09e32 | 2013-12-03 01:22:06 +0100 | [diff] [blame] | 227 | .. seealso:: |
| 228 | |
| 229 | The :func:`asyncio.sleep` function. |
| 230 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 231 | |
Yury Selivanov | 950204d | 2016-05-16 16:23:00 -0400 | [diff] [blame] | 232 | Futures |
| 233 | ------- |
| 234 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 235 | .. method:: AbstractEventLoop.create_future() |
Yury Selivanov | 950204d | 2016-05-16 16:23:00 -0400 | [diff] [blame] | 236 | |
| 237 | Create an :class:`asyncio.Future` object attached to the loop. |
| 238 | |
| 239 | This is a preferred way to create futures in asyncio, as event |
| 240 | loop implementations can provide alternative implementations |
| 241 | of the Future class (with better performance or instrumentation). |
| 242 | |
| 243 | .. versionadded:: 3.5.2 |
| 244 | |
| 245 | |
Yury Selivanov | bb96134 | 2015-06-25 11:54:34 -0400 | [diff] [blame] | 246 | Tasks |
| 247 | ----- |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 248 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 249 | .. method:: AbstractEventLoop.create_task(coro, \*, name=None) |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 250 | |
| 251 | Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in |
| 252 | a future. Return a :class:`Task` object. |
| 253 | |
| 254 | Third-party event loops can use their own subclass of :class:`Task` for |
| 255 | interoperability. In this case, the result type is a subclass of |
| 256 | :class:`Task`. |
| 257 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 258 | If the *name* argument is provided and not ``None``, it is set as the name |
| 259 | of the task using :meth:`Task.set_name`. |
| 260 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 261 | .. versionadded:: 3.4.2 |
| 262 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 263 | .. versionchanged:: 3.8 |
| 264 | Added the ``name`` parameter. |
| 265 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 266 | .. method:: AbstractEventLoop.set_task_factory(factory) |
Yury Selivanov | 7185461 | 2015-05-11 16:28:27 -0400 | [diff] [blame] | 267 | |
| 268 | Set a task factory that will be used by |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 269 | :meth:`AbstractEventLoop.create_task`. |
Yury Selivanov | 7185461 | 2015-05-11 16:28:27 -0400 | [diff] [blame] | 270 | |
| 271 | If *factory* is ``None`` the default task factory will be set. |
| 272 | |
| 273 | If *factory* is a *callable*, it should have a signature matching |
| 274 | ``(loop, coro)``, where *loop* will be a reference to the active |
| 275 | event loop, *coro* will be a coroutine object. The callable |
| 276 | must return an :class:`asyncio.Future` compatible object. |
| 277 | |
| 278 | .. versionadded:: 3.4.4 |
| 279 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 280 | .. method:: AbstractEventLoop.get_task_factory() |
Yury Selivanov | 7185461 | 2015-05-11 16:28:27 -0400 | [diff] [blame] | 281 | |
| 282 | Return a task factory, or ``None`` if the default one is in use. |
| 283 | |
| 284 | .. versionadded:: 3.4.4 |
| 285 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 286 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 287 | Creating connections |
Victor Stinner | 0c6f1ca | 2013-12-03 01:46:39 +0100 | [diff] [blame] | 288 | -------------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 289 | |
Andrew Svetlov | 51eb1c6 | 2017-12-20 20:24:43 +0200 | [diff] [blame] | 290 | .. coroutinemethod:: AbstractEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 291 | |
| 292 | Create a streaming transport connection to a given Internet *host* and |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 293 | *port*: socket family :py:data:`~socket.AF_INET` or |
| 294 | :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified), |
| 295 | socket type :py:data:`~socket.SOCK_STREAM`. *protocol_factory* must be a |
| 296 | callable returning a :ref:`protocol <asyncio-protocol>` instance. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 297 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 298 | This method will try to establish the connection in the background. |
| 299 | When successful, it returns a ``(transport, protocol)`` pair. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 300 | |
| 301 | The chronological synopsis of the underlying operation is as follows: |
| 302 | |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 303 | #. The connection is established, and a :ref:`transport <asyncio-transport>` |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 304 | is created to represent it. |
| 305 | |
| 306 | #. *protocol_factory* is called without arguments and must return a |
Victor Stinner | 9592edb | 2014-02-02 15:03:02 +0100 | [diff] [blame] | 307 | :ref:`protocol <asyncio-protocol>` instance. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 308 | |
| 309 | #. The protocol instance is tied to the transport, and its |
| 310 | :meth:`connection_made` method is called. |
| 311 | |
| 312 | #. The coroutine returns successfully with the ``(transport, protocol)`` |
| 313 | pair. |
| 314 | |
| 315 | The created transport is an implementation-dependent bidirectional stream. |
| 316 | |
| 317 | .. note:: |
| 318 | *protocol_factory* can be any kind of callable, not necessarily |
| 319 | a class. For example, if you want to use a pre-created |
| 320 | protocol instance, you can pass ``lambda: my_protocol``. |
| 321 | |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 322 | Options that change how the connection is created: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 323 | |
| 324 | * *ssl*: if given and not false, a SSL/TLS transport is created |
| 325 | (by default a plain TCP transport is created). If *ssl* is |
| 326 | a :class:`ssl.SSLContext` object, this context is used to create |
| 327 | the transport; if *ssl* is :const:`True`, a context with some |
| 328 | unspecified default settings is used. |
| 329 | |
Berker Peksag | 9c1dba2 | 2014-09-28 00:00:58 +0300 | [diff] [blame] | 330 | .. seealso:: :ref:`SSL/TLS security considerations <ssl-security>` |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 331 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 332 | * *server_hostname*, is only for use together with *ssl*, |
| 333 | and sets or overrides the hostname that the target server's certificate |
| 334 | will be matched against. By default the value of the *host* argument |
| 335 | is used. If *host* is empty, there is no default and you must pass a |
| 336 | value for *server_hostname*. If *server_hostname* is an empty |
| 337 | string, hostname matching is disabled (which is a serious security |
| 338 | risk, allowing for man-in-the-middle-attacks). |
| 339 | |
| 340 | * *family*, *proto*, *flags* are the optional address family, protocol |
| 341 | and flags to be passed through to getaddrinfo() for *host* resolution. |
| 342 | If given, these should all be integers from the corresponding |
| 343 | :mod:`socket` module constants. |
| 344 | |
| 345 | * *sock*, if given, should be an existing, already connected |
| 346 | :class:`socket.socket` object to be used by the transport. |
| 347 | If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags* |
| 348 | and *local_addr* should be specified. |
| 349 | |
| 350 | * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used |
| 351 | to bind the socket to locally. The *local_host* and *local_port* |
| 352 | are looked up using getaddrinfo(), similarly to *host* and *port*. |
| 353 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 354 | * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds |
| 355 | to wait for the SSL handshake to complete before aborting the connection. |
Yury Selivanov | 9602643 | 2018-06-04 11:32:35 -0400 | [diff] [blame] | 356 | ``60.0`` seconds if ``None`` (default). |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 357 | |
| 358 | .. versionadded:: 3.7 |
| 359 | |
| 360 | The *ssl_handshake_timeout* parameter. |
| 361 | |
Victor Stinner | 60208a1 | 2015-09-15 22:41:52 +0200 | [diff] [blame] | 362 | .. versionchanged:: 3.5 |
| 363 | |
| 364 | On Windows with :class:`ProactorEventLoop`, SSL/TLS is now supported. |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 365 | |
Victor Stinner | c8ea813 | 2014-01-23 11:02:09 +0100 | [diff] [blame] | 366 | .. seealso:: |
| 367 | |
| 368 | The :func:`open_connection` function can be used to get a pair of |
| 369 | (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol. |
| 370 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 371 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 372 | .. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None) |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 373 | |
Quentin Dawans | fe4ea9c | 2017-10-30 14:43:02 +0100 | [diff] [blame] | 374 | Create datagram connection: socket family :py:data:`~socket.AF_INET`, |
| 375 | :py:data:`~socket.AF_INET6` or :py:data:`~socket.AF_UNIX` depending on |
| 376 | *host* (or *family* if specified), socket type |
| 377 | :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a |
Guido van Rossum | b9bf913 | 2015-10-05 09:15:28 -0700 | [diff] [blame] | 378 | callable returning a :ref:`protocol <asyncio-protocol>` instance. |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 379 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 380 | This method will try to establish the connection in the background. |
MarcoFalke | 7e0d882 | 2018-06-09 19:09:13 -0400 | [diff] [blame] | 381 | When successful, it returns a ``(transport, protocol)`` pair. |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 382 | |
Guido van Rossum | b9bf913 | 2015-10-05 09:15:28 -0700 | [diff] [blame] | 383 | Options changing how the connection is created: |
| 384 | |
| 385 | * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used |
| 386 | to bind the socket to locally. The *local_host* and *local_port* |
| 387 | are looked up using :meth:`getaddrinfo`. |
| 388 | |
| 389 | * *remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used |
| 390 | to connect the socket to a remote address. The *remote_host* and |
| 391 | *remote_port* are looked up using :meth:`getaddrinfo`. |
| 392 | |
| 393 | * *family*, *proto*, *flags* are the optional address family, protocol |
| 394 | and flags to be passed through to :meth:`getaddrinfo` for *host* |
| 395 | resolution. If given, these should all be integers from the |
| 396 | corresponding :mod:`socket` module constants. |
| 397 | |
| 398 | * *reuse_address* tells the kernel to reuse a local socket in |
| 399 | TIME_WAIT state, without waiting for its natural timeout to |
Serhiy Storchaka | 4adf01c | 2016-10-19 18:30:05 +0300 | [diff] [blame] | 400 | expire. If not specified will automatically be set to ``True`` on |
Guido van Rossum | b9bf913 | 2015-10-05 09:15:28 -0700 | [diff] [blame] | 401 | UNIX. |
| 402 | |
| 403 | * *reuse_port* tells the kernel to allow this endpoint to be bound to the |
| 404 | same port as other existing endpoints are bound to, so long as they all |
| 405 | set this flag when being created. This option is not supported on Windows |
| 406 | and some UNIX's. If the :py:data:`~socket.SO_REUSEPORT` constant is not |
| 407 | defined then this capability is unsupported. |
| 408 | |
| 409 | * *allow_broadcast* tells the kernel to allow this endpoint to send |
| 410 | messages to the broadcast address. |
| 411 | |
| 412 | * *sock* can optionally be specified in order to use a preexisting, |
| 413 | already connected, :class:`socket.socket` object to be used by the |
| 414 | transport. If specified, *local_addr* and *remote_addr* should be omitted |
| 415 | (must be :const:`None`). |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 416 | |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 417 | On Windows with :class:`ProactorEventLoop`, this method is not supported. |
| 418 | |
Victor Stinner | c7edffd | 2014-10-12 11:24:26 +0200 | [diff] [blame] | 419 | See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and |
| 420 | :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples. |
| 421 | |
Romuald Brunet | 0ded580 | 2018-05-14 18:22:00 +0200 | [diff] [blame] | 422 | .. versionchanged:: 3.4.4 |
| 423 | The *family*, *proto*, *flags*, *reuse_address*, *reuse_port, |
| 424 | *allow_broadcast*, and *sock* parameters were added. |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 425 | |
Andrew Svetlov | 51eb1c6 | 2017-12-20 20:24:43 +0200 | [diff] [blame] | 426 | .. coroutinemethod:: AbstractEventLoop.create_unix_connection(protocol_factory, path=None, \*, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None) |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 427 | |
| 428 | Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket |
| 429 | type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket |
| 430 | family is used to communicate between processes on the same machine |
| 431 | efficiently. |
| 432 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 433 | This method will try to establish the connection in the background. |
MarcoFalke | 7e0d882 | 2018-06-09 19:09:13 -0400 | [diff] [blame] | 434 | When successful, it returns a ``(transport, protocol)`` pair. |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 435 | |
Guido van Rossum | 9e80eeb | 2016-11-03 14:17:25 -0700 | [diff] [blame] | 436 | *path* is the name of a UNIX domain socket, and is required unless a *sock* |
Yury Selivanov | 423fd36 | 2017-11-20 17:26:28 -0500 | [diff] [blame] | 437 | parameter is specified. Abstract UNIX sockets, :class:`str`, |
| 438 | :class:`bytes`, and :class:`~pathlib.Path` paths are supported. |
Guido van Rossum | 9e80eeb | 2016-11-03 14:17:25 -0700 | [diff] [blame] | 439 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 440 | See the :meth:`AbstractEventLoop.create_connection` method for parameters. |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 441 | |
| 442 | Availability: UNIX. |
| 443 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 444 | .. versionadded:: 3.7 |
| 445 | |
| 446 | The *ssl_handshake_timeout* parameter. |
| 447 | |
Yury Selivanov | 423fd36 | 2017-11-20 17:26:28 -0500 | [diff] [blame] | 448 | .. versionchanged:: 3.7 |
| 449 | |
Elvis Pranskevichus | c0d062f | 2018-06-08 11:36:00 -0400 | [diff] [blame] | 450 | The *path* parameter can now be a :term:`path-like object`. |
Yury Selivanov | 423fd36 | 2017-11-20 17:26:28 -0500 | [diff] [blame] | 451 | |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 452 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 453 | Creating listening connections |
| 454 | ------------------------------ |
| 455 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 456 | .. coroutinemethod:: AbstractEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 457 | |
Victor Stinner | 33f6abe | 2014-10-12 20:36:04 +0200 | [diff] [blame] | 458 | Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to |
| 459 | *host* and *port*. |
| 460 | |
| 461 | Return a :class:`Server` object, its :attr:`~Server.sockets` attribute |
| 462 | contains created sockets. Use the :meth:`Server.close` method to stop the |
| 463 | server: close listening sockets. |
| 464 | |
| 465 | Parameters: |
| 466 | |
Victor Stinner | 5e4a7d8 | 2015-09-21 18:33:43 +0200 | [diff] [blame] | 467 | * The *host* parameter can be a string, in that case the TCP server is |
| 468 | bound to *host* and *port*. The *host* parameter can also be a sequence |
| 469 | of strings and in that case the TCP server is bound to all hosts of the |
| 470 | sequence. If *host* is an empty string or ``None``, all interfaces are |
| 471 | assumed and a list of multiple sockets will be returned (most likely one |
| 472 | for IPv4 and another one for IPv6). |
Victor Stinner | 33f6abe | 2014-10-12 20:36:04 +0200 | [diff] [blame] | 473 | |
| 474 | * *family* can be set to either :data:`socket.AF_INET` or |
| 475 | :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6. If not set |
| 476 | it will be determined from host (defaults to :data:`socket.AF_UNSPEC`). |
| 477 | |
| 478 | * *flags* is a bitmask for :meth:`getaddrinfo`. |
| 479 | |
| 480 | * *sock* can optionally be specified in order to use a preexisting |
| 481 | socket object. If specified, *host* and *port* should be omitted (must be |
| 482 | :const:`None`). |
| 483 | |
| 484 | * *backlog* is the maximum number of queued connections passed to |
| 485 | :meth:`~socket.socket.listen` (defaults to 100). |
| 486 | |
| 487 | * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the |
| 488 | accepted connections. |
| 489 | |
| 490 | * *reuse_address* tells the kernel to reuse a local socket in |
| 491 | TIME_WAIT state, without waiting for its natural timeout to |
Serhiy Storchaka | 4adf01c | 2016-10-19 18:30:05 +0300 | [diff] [blame] | 492 | expire. If not specified will automatically be set to ``True`` on |
Victor Stinner | 33f6abe | 2014-10-12 20:36:04 +0200 | [diff] [blame] | 493 | UNIX. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 494 | |
Guido van Rossum | b9bf913 | 2015-10-05 09:15:28 -0700 | [diff] [blame] | 495 | * *reuse_port* tells the kernel to allow this endpoint to be bound to the |
| 496 | same port as other existing endpoints are bound to, so long as they all |
| 497 | set this flag when being created. This option is not supported on |
| 498 | Windows. |
| 499 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 500 | * *ssl_handshake_timeout* is (for an SSL server) the time in seconds to wait |
| 501 | for the SSL handshake to complete before aborting the connection. |
Yury Selivanov | 9602643 | 2018-06-04 11:32:35 -0400 | [diff] [blame] | 502 | ``60.0`` seconds if ``None`` (default). |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 503 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 504 | * *start_serving* set to ``True`` (the default) causes the created server |
| 505 | to start accepting connections immediately. When set to ``False``, |
| 506 | the user should await on :meth:`Server.start_serving` or |
| 507 | :meth:`Server.serve_forever` to make the server to start accepting |
| 508 | connections. |
| 509 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 510 | .. versionadded:: 3.7 |
| 511 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 512 | *ssl_handshake_timeout* and *start_serving* parameters. |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 513 | |
Victor Stinner | 60208a1 | 2015-09-15 22:41:52 +0200 | [diff] [blame] | 514 | .. versionchanged:: 3.5 |
| 515 | |
| 516 | On Windows with :class:`ProactorEventLoop`, SSL/TLS is now supported. |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 517 | |
Victor Stinner | c8ea813 | 2014-01-23 11:02:09 +0100 | [diff] [blame] | 518 | .. seealso:: |
| 519 | |
| 520 | The function :func:`start_server` creates a (:class:`StreamReader`, |
| 521 | :class:`StreamWriter`) pair and calls back a function with this pair. |
| 522 | |
Victor Stinner | 7b58a2b | 2015-09-21 18:41:05 +0200 | [diff] [blame] | 523 | .. versionchanged:: 3.5.1 |
Victor Stinner | 5e4a7d8 | 2015-09-21 18:33:43 +0200 | [diff] [blame] | 524 | |
| 525 | The *host* parameter can now be a sequence of strings. |
| 526 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 527 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 528 | .. coroutinemethod:: AbstractEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 529 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 530 | Similar to :meth:`AbstractEventLoop.create_server`, but specific to the |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 531 | socket family :py:data:`~socket.AF_UNIX`. |
| 532 | |
Yury Selivanov | 423fd36 | 2017-11-20 17:26:28 -0500 | [diff] [blame] | 533 | *path* is the name of a UNIX domain socket, and is required unless a *sock* |
| 534 | parameter is specified. Abstract UNIX sockets, :class:`str`, |
| 535 | :class:`bytes`, and :class:`~pathlib.Path` paths are supported. |
| 536 | |
Victor Stinner | a6919aa | 2014-02-19 13:32:34 +0100 | [diff] [blame] | 537 | Availability: UNIX. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 538 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 539 | .. versionadded:: 3.7 |
| 540 | |
Elvis Pranskevichus | c0d062f | 2018-06-08 11:36:00 -0400 | [diff] [blame] | 541 | The *ssl_handshake_timeout* and *start_serving* parameters. |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 542 | |
Yury Selivanov | 423fd36 | 2017-11-20 17:26:28 -0500 | [diff] [blame] | 543 | .. versionchanged:: 3.7 |
| 544 | |
| 545 | The *path* parameter can now be a :class:`~pathlib.Path` object. |
| 546 | |
Andrew Svetlov | 51eb1c6 | 2017-12-20 20:24:43 +0200 | [diff] [blame] | 547 | .. coroutinemethod:: BaseEventLoop.connect_accepted_socket(protocol_factory, sock, \*, ssl=None, ssl_handshake_timeout=None) |
Yury Selivanov | 3b3a141 | 2016-11-07 15:35:25 -0500 | [diff] [blame] | 548 | |
| 549 | Handle an accepted connection. |
| 550 | |
| 551 | This is used by servers that accept connections outside of |
| 552 | asyncio but that use asyncio to handle them. |
| 553 | |
| 554 | Parameters: |
| 555 | |
| 556 | * *sock* is a preexisting socket object returned from an ``accept`` |
| 557 | call. |
| 558 | |
| 559 | * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the |
| 560 | accepted connections. |
| 561 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 562 | * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds to |
| 563 | wait for the SSL handshake to complete before aborting the connection. |
Yury Selivanov | 9602643 | 2018-06-04 11:32:35 -0400 | [diff] [blame] | 564 | ``60.0`` seconds if ``None`` (default). |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 565 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 566 | When completed it returns a ``(transport, protocol)`` pair. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 567 | |
Neil Aspinall | f7686c1 | 2017-12-19 19:45:42 +0000 | [diff] [blame] | 568 | .. versionadded:: 3.7 |
| 569 | |
| 570 | The *ssl_handshake_timeout* parameter. |
| 571 | |
AraHaan | 431665b | 2017-11-21 11:06:26 -0500 | [diff] [blame] | 572 | .. versionadded:: 3.5.3 |
| 573 | |
| 574 | |
Andrew Svetlov | 7c68407 | 2018-01-27 21:22:47 +0200 | [diff] [blame] | 575 | File Transferring |
| 576 | ----------------- |
| 577 | |
Elvis Pranskevichus | ee72ac0 | 2018-01-27 17:11:10 -0500 | [diff] [blame] | 578 | .. coroutinemethod:: AbstractEventLoop.sendfile(transport, file, \ |
Andrew Svetlov | 7c68407 | 2018-01-27 21:22:47 +0200 | [diff] [blame] | 579 | offset=0, count=None, \ |
| 580 | *, fallback=True) |
| 581 | |
| 582 | Send a *file* to *transport*, return the total number of bytes |
| 583 | which were sent. |
| 584 | |
| 585 | The method uses high-performance :meth:`os.sendfile` if available. |
| 586 | |
| 587 | *file* must be a regular file object opened in binary mode. |
| 588 | |
| 589 | *offset* tells from where to start reading the file. If specified, |
| 590 | *count* is the total number of bytes to transmit as opposed to |
| 591 | sending the file until EOF is reached. File position is updated on |
| 592 | return or also in case of error in which case :meth:`file.tell() |
| 593 | <io.IOBase.tell>` can be used to figure out the number of bytes |
| 594 | which were sent. |
| 595 | |
| 596 | *fallback* set to ``True`` makes asyncio to manually read and send |
| 597 | the file when the platform does not support the sendfile syscall |
| 598 | (e.g. Windows or SSL socket on Unix). |
| 599 | |
| 600 | Raise :exc:`SendfileNotAvailableError` if the system does not support |
| 601 | *sendfile* syscall and *fallback* is ``False``. |
| 602 | |
| 603 | .. versionadded:: 3.7 |
| 604 | |
| 605 | |
Yury Selivanov | f111b3d | 2017-12-30 00:35:36 -0500 | [diff] [blame] | 606 | TLS Upgrade |
| 607 | ----------- |
| 608 | |
| 609 | .. coroutinemethod:: AbstractEventLoop.start_tls(transport, protocol, sslcontext, \*, server_side=False, server_hostname=None, ssl_handshake_timeout=None) |
| 610 | |
| 611 | Upgrades an existing connection to TLS. |
| 612 | |
| 613 | Returns a new transport instance, that the *protocol* must start using |
| 614 | immediately after the *await*. The *transport* instance passed to |
| 615 | the *start_tls* method should never be used again. |
| 616 | |
| 617 | Parameters: |
| 618 | |
| 619 | * *transport* and *protocol* instances that methods like |
| 620 | :meth:`~AbstractEventLoop.create_server` and |
| 621 | :meth:`~AbstractEventLoop.create_connection` return. |
| 622 | |
| 623 | * *sslcontext*: a configured instance of :class:`~ssl.SSLContext`. |
| 624 | |
| 625 | * *server_side* pass ``True`` when a server-side connection is being |
| 626 | upgraded (like the one created by :meth:`~AbstractEventLoop.create_server`). |
| 627 | |
| 628 | * *server_hostname*: sets or overrides the host name that the target |
| 629 | server's certificate will be matched against. |
| 630 | |
| 631 | * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds to |
| 632 | wait for the SSL handshake to complete before aborting the connection. |
Yury Selivanov | 9602643 | 2018-06-04 11:32:35 -0400 | [diff] [blame] | 633 | ``60.0`` seconds if ``None`` (default). |
Yury Selivanov | f111b3d | 2017-12-30 00:35:36 -0500 | [diff] [blame] | 634 | |
| 635 | .. versionadded:: 3.7 |
| 636 | |
| 637 | |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 638 | Watch file descriptors |
| 639 | ---------------------- |
| 640 | |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 641 | On Windows with :class:`SelectorEventLoop`, only socket handles are supported |
| 642 | (ex: pipe file descriptors are not supported). |
| 643 | |
| 644 | On Windows with :class:`ProactorEventLoop`, these methods are not supported. |
| 645 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 646 | .. method:: AbstractEventLoop.add_reader(fd, callback, \*args) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 647 | |
| 648 | Start watching the file descriptor for read availability and then call the |
| 649 | *callback* with specified arguments. |
| 650 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 651 | :ref:`Use functools.partial to pass keywords to the callback |
| 652 | <asyncio-pass-keywords>`. |
| 653 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 654 | .. method:: AbstractEventLoop.remove_reader(fd) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 655 | |
| 656 | Stop watching the file descriptor for read availability. |
| 657 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 658 | .. method:: AbstractEventLoop.add_writer(fd, callback, \*args) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 659 | |
| 660 | Start watching the file descriptor for write availability and then call the |
| 661 | *callback* with specified arguments. |
| 662 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 663 | :ref:`Use functools.partial to pass keywords to the callback |
| 664 | <asyncio-pass-keywords>`. |
| 665 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 666 | .. method:: AbstractEventLoop.remove_writer(fd) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 667 | |
| 668 | Stop watching the file descriptor for write availability. |
| 669 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 670 | The :ref:`watch a file descriptor for read events <asyncio-watch-read-event>` |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 671 | example uses the low-level :meth:`AbstractEventLoop.add_reader` method to register |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 672 | the file descriptor of a socket. |
| 673 | |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 674 | |
| 675 | Low-level socket operations |
| 676 | --------------------------- |
| 677 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 678 | .. coroutinemethod:: AbstractEventLoop.sock_recv(sock, nbytes) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 679 | |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 680 | Receive data from the socket. Modeled after blocking |
| 681 | :meth:`socket.socket.recv` method. |
| 682 | |
| 683 | The return value is a bytes object |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 684 | representing the data received. The maximum amount of data to be received |
| 685 | at once is specified by *nbytes*. |
| 686 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 687 | With :class:`SelectorEventLoop` event loop, the socket *sock* must be |
| 688 | non-blocking. |
Victor Stinner | ec2ce09 | 2014-07-29 23:12:22 +0200 | [diff] [blame] | 689 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 690 | .. versionchanged:: 3.7 |
| 691 | Even though the method was always documented as a coroutine |
| 692 | method, before Python 3.7 it returned a :class:`Future`. |
| 693 | Since Python 3.7, this is an ``async def`` method. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 694 | |
Antoine Pitrou | 525f40d | 2017-10-19 21:46:40 +0200 | [diff] [blame] | 695 | .. coroutinemethod:: AbstractEventLoop.sock_recv_into(sock, buf) |
| 696 | |
| 697 | Receive data from the socket. Modeled after blocking |
| 698 | :meth:`socket.socket.recv_into` method. |
| 699 | |
| 700 | The received data is written into *buf* (a writable buffer). |
| 701 | The return value is the number of bytes written. |
| 702 | |
| 703 | With :class:`SelectorEventLoop` event loop, the socket *sock* must be |
| 704 | non-blocking. |
| 705 | |
Antoine Pitrou | 525f40d | 2017-10-19 21:46:40 +0200 | [diff] [blame] | 706 | .. versionadded:: 3.7 |
| 707 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 708 | .. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 709 | |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 710 | Send data to the socket. Modeled after blocking |
| 711 | :meth:`socket.socket.sendall` method. |
| 712 | |
| 713 | The socket must be connected to a remote socket. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 714 | This method continues to send data from *data* until either all data has |
| 715 | been sent or an error occurs. ``None`` is returned on success. On error, |
| 716 | an exception is raised, and there is no way to determine how much data, if |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 717 | any, was successfully processed by the receiving end of the connection. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 718 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 719 | With :class:`SelectorEventLoop` event loop, the socket *sock* must be |
| 720 | non-blocking. |
Victor Stinner | ec2ce09 | 2014-07-29 23:12:22 +0200 | [diff] [blame] | 721 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 722 | .. versionchanged:: 3.7 |
| 723 | Even though the method was always documented as a coroutine |
| 724 | method, before Python 3.7 it returned an :class:`Future`. |
| 725 | Since Python 3.7, this is an ``async def`` method. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 726 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 727 | .. coroutinemethod:: AbstractEventLoop.sock_connect(sock, address) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 728 | |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 729 | Connect to a remote socket at *address*. Modeled after |
| 730 | blocking :meth:`socket.socket.connect` method. |
Victor Stinner | 1b0580b | 2014-02-13 09:24:37 +0100 | [diff] [blame] | 731 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 732 | With :class:`SelectorEventLoop` event loop, the socket *sock* must be |
| 733 | non-blocking. |
Victor Stinner | ec2ce09 | 2014-07-29 23:12:22 +0200 | [diff] [blame] | 734 | |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 735 | .. versionchanged:: 3.5.2 |
| 736 | ``address`` no longer needs to be resolved. ``sock_connect`` |
| 737 | will try to check if the *address* is already resolved by calling |
| 738 | :func:`socket.inet_pton`. If not, |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 739 | :meth:`AbstractEventLoop.getaddrinfo` will be used to resolve the |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 740 | *address*. |
| 741 | |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 742 | .. seealso:: |
| 743 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 744 | :meth:`AbstractEventLoop.create_connection` |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 745 | and :func:`asyncio.open_connection() <open_connection>`. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 746 | |
| 747 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 748 | .. coroutinemethod:: AbstractEventLoop.sock_accept(sock) |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 749 | |
Yury Selivanov | 55c5084 | 2016-06-08 12:48:15 -0400 | [diff] [blame] | 750 | Accept a connection. Modeled after blocking |
| 751 | :meth:`socket.socket.accept`. |
| 752 | |
| 753 | The socket must be bound to an address and listening |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 754 | for connections. The return value is a pair ``(conn, address)`` where *conn* |
| 755 | is a *new* socket object usable to send and receive data on the connection, |
| 756 | and *address* is the address bound to the socket on the other end of the |
| 757 | connection. |
| 758 | |
Victor Stinner | ec2ce09 | 2014-07-29 23:12:22 +0200 | [diff] [blame] | 759 | The socket *sock* must be non-blocking. |
| 760 | |
Yury Selivanov | 19a44f6 | 2017-12-14 20:53:26 -0500 | [diff] [blame] | 761 | .. versionchanged:: 3.7 |
| 762 | Even though the method was always documented as a coroutine |
| 763 | method, before Python 3.7 it returned a :class:`Future`. |
| 764 | Since Python 3.7, this is an ``async def`` method. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 765 | |
| 766 | .. seealso:: |
| 767 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 768 | :meth:`AbstractEventLoop.create_server` and :func:`start_server`. |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 769 | |
Andrew Svetlov | 6b5a279 | 2018-01-16 19:59:34 +0200 | [diff] [blame] | 770 | .. coroutinemethod:: AbstractEventLoop.sock_sendfile(sock, file, \ |
| 771 | offset=0, count=None, \ |
| 772 | *, fallback=True) |
| 773 | |
| 774 | Send a file using high-performance :mod:`os.sendfile` if possible |
| 775 | and return the total number of bytes which were sent. |
| 776 | |
| 777 | Asynchronous version of :meth:`socket.socket.sendfile`. |
| 778 | |
| 779 | *sock* must be non-blocking :class:`~socket.socket` of |
| 780 | :const:`socket.SOCK_STREAM` type. |
| 781 | |
| 782 | *file* must be a regular file object opened in binary mode. |
| 783 | |
| 784 | *offset* tells from where to start reading the file. If specified, |
| 785 | *count* is the total number of bytes to transmit as opposed to |
| 786 | sending the file until EOF is reached. File position is updated on |
| 787 | return or also in case of error in which case :meth:`file.tell() |
| 788 | <io.IOBase.tell>` can be used to figure out the number of bytes |
| 789 | which were sent. |
| 790 | |
| 791 | *fallback* set to ``True`` makes asyncio to manually read and send |
| 792 | the file when the platform does not support the sendfile syscall |
| 793 | (e.g. Windows or SSL socket on Unix). |
| 794 | |
Andrew Svetlov | 7464e87 | 2018-01-19 20:04:29 +0200 | [diff] [blame] | 795 | Raise :exc:`SendfileNotAvailableError` if the system does not support |
Andrew Svetlov | 6b5a279 | 2018-01-16 19:59:34 +0200 | [diff] [blame] | 796 | *sendfile* syscall and *fallback* is ``False``. |
| 797 | |
| 798 | .. versionadded:: 3.7 |
| 799 | |
Victor Stinner | c1567df | 2014-02-08 23:22:58 +0100 | [diff] [blame] | 800 | |
| 801 | Resolve host name |
| 802 | ----------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 803 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 804 | .. coroutinemethod:: AbstractEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 805 | |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 806 | This method is a :ref:`coroutine <coroutine>`, similar to |
| 807 | :meth:`socket.getaddrinfo` function but non-blocking. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 808 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 809 | .. coroutinemethod:: AbstractEventLoop.getnameinfo(sockaddr, flags=0) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 810 | |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 811 | This method is a :ref:`coroutine <coroutine>`, similar to |
| 812 | :meth:`socket.getnameinfo` function but non-blocking. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 813 | |
Yury Selivanov | bec2372 | 2018-01-28 14:09:40 -0500 | [diff] [blame] | 814 | .. versionchanged:: 3.7 |
| 815 | Both *getaddrinfo* and *getnameinfo* methods were always documented |
| 816 | to return a coroutine, but prior to Python 3.7 they were, in fact, |
| 817 | returning :class:`asyncio.Future` objects. Starting with Python 3.7 |
| 818 | both methods are coroutines. |
| 819 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 820 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 821 | Connect pipes |
| 822 | ------------- |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 823 | |
Victor Stinner | 41f3c3f | 2014-08-31 14:47:37 +0200 | [diff] [blame] | 824 | On Windows with :class:`SelectorEventLoop`, these methods are not supported. |
| 825 | Use :class:`ProactorEventLoop` to support pipes on Windows. |
| 826 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 827 | .. coroutinemethod:: AbstractEventLoop.connect_read_pipe(protocol_factory, pipe) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 828 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 829 | Register read pipe in eventloop. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 830 | |
| 831 | *protocol_factory* should instantiate object with :class:`Protocol` |
Victor Stinner | a5b257a | 2014-05-29 00:14:03 +0200 | [diff] [blame] | 832 | interface. *pipe* is a :term:`file-like object <file object>`. |
| 833 | Return pair ``(transport, protocol)``, where *transport* supports the |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 834 | :class:`ReadTransport` interface. |
| 835 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 836 | With :class:`SelectorEventLoop` event loop, the *pipe* is set to |
| 837 | non-blocking mode. |
| 838 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 839 | .. coroutinemethod:: AbstractEventLoop.connect_write_pipe(protocol_factory, pipe) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 840 | |
| 841 | Register write pipe in eventloop. |
| 842 | |
| 843 | *protocol_factory* should instantiate object with :class:`BaseProtocol` |
Victor Stinner | 2cef300 | 2014-10-23 22:38:46 +0200 | [diff] [blame] | 844 | interface. *pipe* is :term:`file-like object <file object>`. |
| 845 | Return pair ``(transport, protocol)``, where *transport* supports |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 846 | :class:`WriteTransport` interface. |
| 847 | |
Victor Stinner | d84fd73 | 2014-08-26 01:01:59 +0200 | [diff] [blame] | 848 | With :class:`SelectorEventLoop` event loop, the *pipe* is set to |
| 849 | non-blocking mode. |
| 850 | |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 851 | .. seealso:: |
| 852 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 853 | The :meth:`AbstractEventLoop.subprocess_exec` and |
| 854 | :meth:`AbstractEventLoop.subprocess_shell` methods. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 855 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 856 | |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 857 | UNIX signals |
| 858 | ------------ |
| 859 | |
| 860 | Availability: UNIX only. |
| 861 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 862 | .. method:: AbstractEventLoop.add_signal_handler(signum, callback, \*args) |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 863 | |
| 864 | Add a handler for a signal. |
| 865 | |
| 866 | Raise :exc:`ValueError` if the signal number is invalid or uncatchable. |
| 867 | Raise :exc:`RuntimeError` if there is a problem setting up the handler. |
| 868 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 869 | :ref:`Use functools.partial to pass keywords to the callback |
| 870 | <asyncio-pass-keywords>`. |
| 871 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 872 | .. method:: AbstractEventLoop.remove_signal_handler(sig) |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 873 | |
| 874 | Remove a handler for a signal. |
| 875 | |
| 876 | Return ``True`` if a signal handler was removed, ``False`` if not. |
| 877 | |
| 878 | .. seealso:: |
| 879 | |
| 880 | The :mod:`signal` module. |
| 881 | |
| 882 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 883 | Executor |
| 884 | -------- |
| 885 | |
| 886 | Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or |
| 887 | pool of processes). By default, an event loop uses a thread pool executor |
| 888 | (:class:`~concurrent.futures.ThreadPoolExecutor`). |
| 889 | |
Yury Selivanov | bec2372 | 2018-01-28 14:09:40 -0500 | [diff] [blame] | 890 | .. method:: AbstractEventLoop.run_in_executor(executor, func, \*args) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 891 | |
Andrew Svetlov | 1c62b52 | 2015-10-01 09:48:08 +0300 | [diff] [blame] | 892 | Arrange for a *func* to be called in the specified executor. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 893 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 894 | The *executor* argument should be an :class:`~concurrent.futures.Executor` |
| 895 | instance. The default executor is used if *executor* is ``None``. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 896 | |
Andrew Svetlov | 1c62b52 | 2015-10-01 09:48:08 +0300 | [diff] [blame] | 897 | :ref:`Use functools.partial to pass keywords to the *func* |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 898 | <asyncio-pass-keywords>`. |
| 899 | |
Yury Selivanov | bec2372 | 2018-01-28 14:09:40 -0500 | [diff] [blame] | 900 | This method returns a :class:`asyncio.Future` object. |
| 901 | |
Yury Selivanov | e8a6045 | 2016-10-21 17:40:42 -0400 | [diff] [blame] | 902 | .. versionchanged:: 3.5.3 |
| 903 | :meth:`BaseEventLoop.run_in_executor` no longer configures the |
| 904 | ``max_workers`` of the thread pool executor it creates, instead |
| 905 | leaving it up to the thread pool executor |
| 906 | (:class:`~concurrent.futures.ThreadPoolExecutor`) to set the |
| 907 | default. |
| 908 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 909 | .. method:: AbstractEventLoop.set_default_executor(executor) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 910 | |
Elvis Pranskevichus | 22d2508 | 2018-07-30 11:42:43 +0100 | [diff] [blame] | 911 | Set *executor* as the default executor used by :meth:`run_in_executor`. |
| 912 | *executor* should be an instance of |
| 913 | :class:`~concurrent.futures.ThreadPoolExecutor`. |
| 914 | |
| 915 | .. deprecated:: 3.8 |
| 916 | Using an executor that is not an instance of |
| 917 | :class:`~concurrent.futures.ThreadPoolExecutor` is deprecated and |
| 918 | will trigger an error in Python 3.9. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 919 | |
| 920 | |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 921 | Error Handling API |
| 922 | ------------------ |
| 923 | |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 924 | Allows customizing how exceptions are handled in the event loop. |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 925 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 926 | .. method:: AbstractEventLoop.set_exception_handler(handler) |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 927 | |
| 928 | Set *handler* as the new event loop exception handler. |
| 929 | |
| 930 | If *handler* is ``None``, the default exception handler will |
| 931 | be set. |
| 932 | |
| 933 | If *handler* is a callable object, it should have a |
| 934 | matching signature to ``(loop, context)``, where ``loop`` |
| 935 | will be a reference to the active event loop, ``context`` |
| 936 | will be a ``dict`` object (see :meth:`call_exception_handler` |
| 937 | documentation for details about context). |
| 938 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 939 | .. method:: AbstractEventLoop.get_exception_handler() |
Yury Selivanov | 950204d | 2016-05-16 16:23:00 -0400 | [diff] [blame] | 940 | |
| 941 | Return the exception handler, or ``None`` if the default one |
| 942 | is in use. |
| 943 | |
| 944 | .. versionadded:: 3.5.2 |
| 945 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 946 | .. method:: AbstractEventLoop.default_exception_handler(context) |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 947 | |
| 948 | Default exception handler. |
| 949 | |
| 950 | This is called when an exception occurs and no exception |
| 951 | handler is set, and can be called by a custom exception |
| 952 | handler that wants to defer to the default behavior. |
| 953 | |
| 954 | *context* parameter has the same meaning as in |
| 955 | :meth:`call_exception_handler`. |
| 956 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 957 | .. method:: AbstractEventLoop.call_exception_handler(context) |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 958 | |
| 959 | Call the current event loop exception handler. |
| 960 | |
| 961 | *context* is a ``dict`` object containing the following keys |
| 962 | (new keys may be introduced later): |
| 963 | |
| 964 | * 'message': Error message; |
| 965 | * 'exception' (optional): Exception object; |
| 966 | * 'future' (optional): :class:`asyncio.Future` instance; |
| 967 | * 'handle' (optional): :class:`asyncio.Handle` instance; |
| 968 | * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance; |
| 969 | * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance; |
| 970 | * 'socket' (optional): :class:`socket.socket` instance. |
| 971 | |
| 972 | .. note:: |
| 973 | |
| 974 | Note: this method should not be overloaded in subclassed |
| 975 | event loops. For any custom exception handling, use |
| 976 | :meth:`set_exception_handler()` method. |
| 977 | |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 978 | Debug mode |
| 979 | ---------- |
| 980 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 981 | .. method:: AbstractEventLoop.get_debug() |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 982 | |
Victor Stinner | 7b7120e | 2014-06-23 00:12:14 +0200 | [diff] [blame] | 983 | Get the debug mode (:class:`bool`) of the event loop. |
| 984 | |
| 985 | The default value is ``True`` if the environment variable |
| 986 | :envvar:`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False`` |
| 987 | otherwise. |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 988 | |
Victor Stinner | 64d750b | 2014-06-18 03:25:23 +0200 | [diff] [blame] | 989 | .. versionadded:: 3.4.2 |
| 990 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 991 | .. method:: AbstractEventLoop.set_debug(enabled: bool) |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 992 | |
| 993 | Set the debug mode of the event loop. |
| 994 | |
Victor Stinner | 64d750b | 2014-06-18 03:25:23 +0200 | [diff] [blame] | 995 | .. versionadded:: 3.4.2 |
| 996 | |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 997 | .. seealso:: |
| 998 | |
Victor Stinner | 62511fd | 2014-06-23 00:36:11 +0200 | [diff] [blame] | 999 | The :ref:`debug mode of asyncio <asyncio-debug-mode>`. |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 1000 | |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1001 | Server |
| 1002 | ------ |
| 1003 | |
Victor Stinner | 8ebeb03 | 2014-07-11 23:47:40 +0200 | [diff] [blame] | 1004 | .. class:: Server |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1005 | |
Victor Stinner | 8ebeb03 | 2014-07-11 23:47:40 +0200 | [diff] [blame] | 1006 | Server listening on sockets. |
| 1007 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 1008 | Object created by :meth:`AbstractEventLoop.create_server`, |
| 1009 | :meth:`AbstractEventLoop.create_unix_server`, :func:`start_server`, |
| 1010 | and :func:`start_unix_server` functions. Don't instantiate the class |
| 1011 | directly. |
| 1012 | |
| 1013 | *Server* objects are asynchronous context managers. When used in an |
| 1014 | ``async with`` statement, it's guaranteed that the Server object is |
| 1015 | closed and not accepting new connections when the ``async with`` |
| 1016 | statement is completed:: |
| 1017 | |
| 1018 | srv = await loop.create_server(...) |
| 1019 | |
| 1020 | async with srv: |
| 1021 | # some code |
| 1022 | |
| 1023 | # At this point, srv is closed and no longer accepts new connections. |
| 1024 | |
| 1025 | |
| 1026 | .. versionchanged:: 3.7 |
| 1027 | Server object is an asynchronous context manager since Python 3.7. |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1028 | |
| 1029 | .. method:: close() |
| 1030 | |
Victor Stinner | 4bfb14a | 2014-07-12 03:20:24 +0200 | [diff] [blame] | 1031 | Stop serving: close listening sockets and set the :attr:`sockets` |
| 1032 | attribute to ``None``. |
| 1033 | |
Berker Peksag | 49c9edf | 2016-01-20 07:14:22 +0200 | [diff] [blame] | 1034 | The sockets that represent existing incoming client connections are left |
| 1035 | open. |
Victor Stinner | 8ebeb03 | 2014-07-11 23:47:40 +0200 | [diff] [blame] | 1036 | |
Berker Peksag | 49c9edf | 2016-01-20 07:14:22 +0200 | [diff] [blame] | 1037 | The server is closed asynchronously, use the :meth:`wait_closed` |
| 1038 | coroutine to wait until the server is closed. |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1039 | |
Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) | 1634fc2 | 2017-12-30 20:39:32 +0530 | [diff] [blame] | 1040 | .. method:: get_loop() |
| 1041 | |
| 1042 | Gives the event loop associated with the server object. |
| 1043 | |
| 1044 | .. versionadded:: 3.7 |
| 1045 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 1046 | .. coroutinemethod:: start_serving() |
| 1047 | |
| 1048 | Start accepting connections. |
| 1049 | |
| 1050 | This method is idempotent, so it can be called when |
| 1051 | the server is already being serving. |
| 1052 | |
| 1053 | The new *start_serving* keyword-only parameter to |
| 1054 | :meth:`AbstractEventLoop.create_server` and |
| 1055 | :meth:`asyncio.start_server` allows to create a Server object |
| 1056 | that is not accepting connections right away. In which case |
| 1057 | this method, or :meth:`Server.serve_forever` can be used |
| 1058 | to make the Server object to start accepting connections. |
| 1059 | |
| 1060 | .. versionadded:: 3.7 |
| 1061 | |
| 1062 | .. coroutinemethod:: serve_forever() |
| 1063 | |
| 1064 | Start accepting connections until the coroutine is cancelled. |
| 1065 | Cancellation of ``serve_forever`` task causes the server |
| 1066 | to be closed. |
| 1067 | |
| 1068 | This method can be called if the server is already accepting |
| 1069 | connections. Only one ``serve_forever`` task can exist per |
| 1070 | one *Server* object. |
| 1071 | |
| 1072 | Example:: |
| 1073 | |
| 1074 | async def client_connected(reader, writer): |
| 1075 | # Communicate with the client with |
| 1076 | # reader/writer streams. For example: |
| 1077 | await reader.readline() |
| 1078 | |
| 1079 | async def main(host, port): |
| 1080 | srv = await asyncio.start_server( |
| 1081 | client_connected, host, port) |
Andrew Svetlov | 17ab8f0 | 2018-02-17 19:44:35 +0200 | [diff] [blame] | 1082 | await srv.serve_forever() |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 1083 | |
| 1084 | asyncio.run(main('127.0.0.1', 0)) |
| 1085 | |
| 1086 | .. versionadded:: 3.7 |
| 1087 | |
| 1088 | .. method:: is_serving() |
| 1089 | |
| 1090 | Return ``True`` if the server is accepting new connections. |
| 1091 | |
| 1092 | .. versionadded:: 3.7 |
| 1093 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 1094 | .. coroutinemethod:: wait_closed() |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1095 | |
Victor Stinner | 8ebeb03 | 2014-07-11 23:47:40 +0200 | [diff] [blame] | 1096 | Wait until the :meth:`close` method completes. |
| 1097 | |
Victor Stinner | 8ebeb03 | 2014-07-11 23:47:40 +0200 | [diff] [blame] | 1098 | .. attribute:: sockets |
| 1099 | |
| 1100 | List of :class:`socket.socket` objects the server is listening to, or |
| 1101 | ``None`` if the server is closed. |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1102 | |
Yury Selivanov | c9070d0 | 2018-01-25 18:08:09 -0500 | [diff] [blame] | 1103 | .. versionchanged:: 3.7 |
| 1104 | Prior to Python 3.7 ``Server.sockets`` used to return the |
| 1105 | internal list of server's sockets directly. In 3.7 a copy |
| 1106 | of that list is returned. |
| 1107 | |
Victor Stinner | 8c462c5 | 2014-01-24 18:11:43 +0100 | [diff] [blame] | 1108 | |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 1109 | Handle |
| 1110 | ------ |
| 1111 | |
| 1112 | .. class:: Handle |
| 1113 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1114 | A callback wrapper object returned by :func:`AbstractEventLoop.call_soon`, |
Andrew Svetlov | 3d4dbd8 | 2018-02-01 19:59:32 +0200 | [diff] [blame] | 1115 | :func:`AbstractEventLoop.call_soon_threadsafe`. |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 1116 | |
| 1117 | .. method:: cancel() |
| 1118 | |
Yury Selivanov | 1096f76 | 2015-06-25 13:49:52 -0400 | [diff] [blame] | 1119 | Cancel the call. If the callback is already canceled or executed, |
| 1120 | this method has no effect. |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 1121 | |
Marat Sharafutdinov | 69cfed1 | 2017-11-07 12:06:05 +0300 | [diff] [blame] | 1122 | .. method:: cancelled() |
| 1123 | |
| 1124 | Return ``True`` if the call was cancelled. |
| 1125 | |
| 1126 | .. versionadded:: 3.7 |
| 1127 | |
Andrew Svetlov | 3d4dbd8 | 2018-02-01 19:59:32 +0200 | [diff] [blame] | 1128 | .. class:: TimerHandle |
| 1129 | |
| 1130 | A callback wrapper object returned by :func:`AbstractEventLoop.call_later`, |
| 1131 | and :func:`AbstractEventLoop.call_at`. |
| 1132 | |
| 1133 | The class is inherited from :class:`Handle`. |
| 1134 | |
| 1135 | .. method:: when() |
| 1136 | |
| 1137 | Return a scheduled callback time as :class:`float` seconds. |
| 1138 | |
| 1139 | The time is an absolute timestamp, using the same time |
| 1140 | reference as :meth:`AbstractEventLoop.time`. |
| 1141 | |
| 1142 | .. versionadded:: 3.7 |
| 1143 | |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 1144 | |
Andrew Svetlov | 7464e87 | 2018-01-19 20:04:29 +0200 | [diff] [blame] | 1145 | SendfileNotAvailableError |
| 1146 | ------------------------- |
| 1147 | |
| 1148 | |
| 1149 | .. exception:: SendfileNotAvailableError |
| 1150 | |
| 1151 | Sendfile syscall is not available, subclass of :exc:`RuntimeError`. |
| 1152 | |
Sam Dunster | 65a3470 | 2018-03-27 17:47:38 -0700 | [diff] [blame] | 1153 | Raised if the OS does not support sendfile syscall for |
Andrew Svetlov | 7464e87 | 2018-01-19 20:04:29 +0200 | [diff] [blame] | 1154 | given socket or file type. |
| 1155 | |
| 1156 | |
Victor Stinner | 6888b96 | 2014-10-11 16:15:58 +0200 | [diff] [blame] | 1157 | Event loop examples |
Victor Stinner | a092a61 | 2015-01-09 15:58:41 +0100 | [diff] [blame] | 1158 | ------------------- |
Yury Selivanov | 43ee1c1 | 2014-02-19 20:58:44 -0500 | [diff] [blame] | 1159 | |
Victor Stinner | 3e09e32 | 2013-12-03 01:22:06 +0100 | [diff] [blame] | 1160 | .. _asyncio-hello-world-callback: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1161 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1162 | Hello World with call_soon() |
Victor Stinner | a092a61 | 2015-01-09 15:58:41 +0100 | [diff] [blame] | 1163 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1164 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1165 | Example using the :meth:`AbstractEventLoop.call_soon` method to schedule a |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1166 | callback. The callback displays ``"Hello World"`` and then stops the event |
| 1167 | loop:: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1168 | |
| 1169 | import asyncio |
| 1170 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1171 | def hello_world(loop): |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1172 | print('Hello World') |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1173 | loop.stop() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1174 | |
| 1175 | loop = asyncio.get_event_loop() |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1176 | |
| 1177 | # Schedule a call to hello_world() |
| 1178 | loop.call_soon(hello_world, loop) |
| 1179 | |
| 1180 | # Blocking call interrupted by loop.stop() |
| 1181 | loop.run_forever() |
| 1182 | loop.close() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1183 | |
Victor Stinner | 3e09e32 | 2013-12-03 01:22:06 +0100 | [diff] [blame] | 1184 | .. seealso:: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1185 | |
Victor Stinner | 6888b96 | 2014-10-11 16:15:58 +0200 | [diff] [blame] | 1186 | The :ref:`Hello World coroutine <asyncio-hello-world-coroutine>` example |
| 1187 | uses a :ref:`coroutine <coroutine>`. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 1188 | |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 1189 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1190 | .. _asyncio-date-callback: |
| 1191 | |
| 1192 | Display the current date with call_later() |
Victor Stinner | a092a61 | 2015-01-09 15:58:41 +0100 | [diff] [blame] | 1193 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1194 | |
| 1195 | Example of callback displaying the current date every second. The callback uses |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1196 | the :meth:`AbstractEventLoop.call_later` method to reschedule itself during 5 |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 1197 | seconds, and then stops the event loop:: |
| 1198 | |
| 1199 | import asyncio |
| 1200 | import datetime |
| 1201 | |
| 1202 | def display_date(end_time, loop): |
| 1203 | print(datetime.datetime.now()) |
| 1204 | if (loop.time() + 1.0) < end_time: |
| 1205 | loop.call_later(1, display_date, end_time, loop) |
| 1206 | else: |
| 1207 | loop.stop() |
| 1208 | |
| 1209 | loop = asyncio.get_event_loop() |
| 1210 | |
| 1211 | # Schedule the first call to display_date() |
| 1212 | end_time = loop.time() + 5.0 |
| 1213 | loop.call_soon(display_date, end_time, loop) |
| 1214 | |
| 1215 | # Blocking call interrupted by loop.stop() |
| 1216 | loop.run_forever() |
| 1217 | loop.close() |
| 1218 | |
| 1219 | .. seealso:: |
| 1220 | |
| 1221 | The :ref:`coroutine displaying the current date |
| 1222 | <asyncio-date-coroutine>` example uses a :ref:`coroutine |
| 1223 | <coroutine>`. |
| 1224 | |
| 1225 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1226 | .. _asyncio-watch-read-event: |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 1227 | |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1228 | Watch a file descriptor for read events |
Victor Stinner | a092a61 | 2015-01-09 15:58:41 +0100 | [diff] [blame] | 1229 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1230 | |
| 1231 | Wait until a file descriptor received some data using the |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1232 | :meth:`AbstractEventLoop.add_reader` method and then close the event loop:: |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1233 | |
| 1234 | import asyncio |
Victor Stinner | ac577d7 | 2017-11-28 21:33:20 +0100 | [diff] [blame] | 1235 | from socket import socketpair |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1236 | |
| 1237 | # Create a pair of connected file descriptors |
Victor Stinner | ccd8e34 | 2014-10-11 16:30:02 +0200 | [diff] [blame] | 1238 | rsock, wsock = socketpair() |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1239 | loop = asyncio.get_event_loop() |
| 1240 | |
| 1241 | def reader(): |
| 1242 | data = rsock.recv(100) |
| 1243 | print("Received:", data.decode()) |
Victor Stinner | 2cef300 | 2014-10-23 22:38:46 +0200 | [diff] [blame] | 1244 | # We are done: unregister the file descriptor |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1245 | loop.remove_reader(rsock) |
| 1246 | # Stop the event loop |
| 1247 | loop.stop() |
| 1248 | |
Victor Stinner | 2cef300 | 2014-10-23 22:38:46 +0200 | [diff] [blame] | 1249 | # Register the file descriptor for read event |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1250 | loop.add_reader(rsock, reader) |
| 1251 | |
| 1252 | # Simulate the reception of data from the network |
| 1253 | loop.call_soon(wsock.send, 'abc'.encode()) |
| 1254 | |
| 1255 | # Run the event loop |
| 1256 | loop.run_forever() |
| 1257 | |
| 1258 | # We are done, close sockets and the event loop |
| 1259 | rsock.close() |
| 1260 | wsock.close() |
| 1261 | loop.close() |
| 1262 | |
| 1263 | .. seealso:: |
| 1264 | |
| 1265 | The :ref:`register an open socket to wait for data using a protocol |
| 1266 | <asyncio-register-socket>` example uses a low-level protocol created by the |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1267 | :meth:`AbstractEventLoop.create_connection` method. |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1268 | |
| 1269 | The :ref:`register an open socket to wait for data using streams |
| 1270 | <asyncio-register-socket-streams>` example uses high-level streams |
| 1271 | created by the :func:`open_connection` function in a coroutine. |
| 1272 | |
| 1273 | |
| 1274 | Set signal handlers for SIGINT and SIGTERM |
Victor Stinner | a092a61 | 2015-01-09 15:58:41 +0100 | [diff] [blame] | 1275 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Victor Stinner | 04e6df3 | 2014-10-11 16:16:27 +0200 | [diff] [blame] | 1276 | |
| 1277 | Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM` using |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 1278 | the :meth:`AbstractEventLoop.add_signal_handler` method:: |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 1279 | |
| 1280 | import asyncio |
| 1281 | import functools |
| 1282 | import os |
| 1283 | import signal |
| 1284 | |
| 1285 | def ask_exit(signame): |
| 1286 | print("got signal %s: exit" % signame) |
| 1287 | loop.stop() |
| 1288 | |
| 1289 | loop = asyncio.get_event_loop() |
| 1290 | for signame in ('SIGINT', 'SIGTERM'): |
| 1291 | loop.add_signal_handler(getattr(signal, signame), |
| 1292 | functools.partial(ask_exit, signame)) |
| 1293 | |
Serhiy Storchaka | 0424eaf | 2015-09-12 17:45:25 +0300 | [diff] [blame] | 1294 | print("Event loop running forever, press Ctrl+C to interrupt.") |
Victor Stinner | 8b86348 | 2014-01-27 10:07:50 +0100 | [diff] [blame] | 1295 | print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid()) |
Victor Stinner | 63b21a8 | 2014-07-05 15:38:59 +0200 | [diff] [blame] | 1296 | try: |
| 1297 | loop.run_forever() |
| 1298 | finally: |
| 1299 | loop.close() |
Victor Stinner | 2cef300 | 2014-10-23 22:38:46 +0200 | [diff] [blame] | 1300 | |
| 1301 | This example only works on UNIX. |