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 | |
| 3 | Tasks and coroutines |
| 4 | ==================== |
| 5 | |
lf | 627d2c8 | 2017-07-25 17:03:51 -0600 | [diff] [blame] | 6 | **Source code:** :source:`Lib/asyncio/tasks.py` |
| 7 | |
| 8 | **Source code:** :source:`Lib/asyncio/coroutines.py` |
| 9 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 10 | .. _coroutine: |
| 11 | |
| 12 | Coroutines |
| 13 | ---------- |
| 14 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 15 | Coroutines used with :mod:`asyncio` may be implemented using the |
| 16 | :keyword:`async def` statement, or by using :term:`generators <generator>`. |
| 17 | The :keyword:`async def` type of coroutine was added in Python 3.5, and |
| 18 | is recommended if there is no need to support older Python versions. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 19 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 20 | Generator-based coroutines should be decorated with :func:`@asyncio.coroutine |
| 21 | <asyncio.coroutine>`, although this is not strictly enforced. |
| 22 | The decorator enables compatibility with :keyword:`async def` coroutines, |
| 23 | and also serves as documentation. Generator-based |
| 24 | coroutines use the ``yield from`` syntax introduced in :pep:`380`, |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 25 | instead of the original ``yield`` syntax. |
| 26 | |
| 27 | The word "coroutine", like the word "generator", is used for two |
| 28 | different (though related) concepts: |
| 29 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 30 | - The function that defines a coroutine |
| 31 | (a function definition using :keyword:`async def` or |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 32 | decorated with ``@asyncio.coroutine``). If disambiguation is needed |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 33 | we will call this a *coroutine function* (:func:`iscoroutinefunction` |
| 34 | returns ``True``). |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 35 | |
| 36 | - The object obtained by calling a coroutine function. This object |
| 37 | represents a computation or an I/O operation (usually a combination) |
| 38 | that will complete eventually. If disambiguation is needed we will |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 39 | call it a *coroutine object* (:func:`iscoroutine` returns ``True``). |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 40 | |
| 41 | Things a coroutine can do: |
| 42 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 43 | - ``result = await future`` or ``result = yield from future`` -- |
| 44 | suspends the coroutine until the |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 45 | future is done, then returns the future's result, or raises an |
| 46 | exception, which will be propagated. (If the future is cancelled, |
| 47 | it will raise a ``CancelledError`` exception.) Note that tasks are |
| 48 | futures, and everything said about futures also applies to tasks. |
| 49 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 50 | - ``result = await coroutine`` or ``result = yield from coroutine`` -- |
| 51 | wait for another coroutine to |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 52 | produce a result (or raise an exception, which will be propagated). |
| 53 | The ``coroutine`` expression must be a *call* to another coroutine. |
| 54 | |
| 55 | - ``return expression`` -- produce a result to the coroutine that is |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 56 | waiting for this one using :keyword:`await` or ``yield from``. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 57 | |
| 58 | - ``raise exception`` -- raise an exception in the coroutine that is |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 59 | waiting for this one using :keyword:`await` or ``yield from``. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 60 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 61 | Calling a coroutine does not start its code running -- |
| 62 | the coroutine object returned by the call doesn't do anything until you |
| 63 | schedule its execution. There are two basic ways to start it running: |
| 64 | call ``await coroutine`` or ``yield from coroutine`` from another coroutine |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 65 | (assuming the other coroutine is already running!), or schedule its execution |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 66 | using the :func:`ensure_future` function or the :meth:`AbstractEventLoop.create_task` |
Victor Stinner | 337e03f | 2014-08-11 01:11:13 +0200 | [diff] [blame] | 67 | method. |
| 68 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 69 | |
| 70 | Coroutines (and tasks) can only run when the event loop is running. |
| 71 | |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 72 | .. decorator:: coroutine |
| 73 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 74 | Decorator to mark generator-based coroutines. This enables |
| 75 | the generator use :keyword:`!yield from` to call :keyword:`async |
| 76 | def` coroutines, and also enables the generator to be called by |
| 77 | :keyword:`async def` coroutines, for instance using an |
| 78 | :keyword:`await` expression. |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 79 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 80 | There is no need to decorate :keyword:`async def` coroutines themselves. |
| 81 | |
| 82 | If the generator is not yielded from before it is destroyed, an error |
Victor Stinner | db39a0d | 2014-01-16 18:58:01 +0100 | [diff] [blame] | 83 | message is logged. See :ref:`Detect coroutines never scheduled |
| 84 | <asyncio-coroutine-not-scheduled>`. |
| 85 | |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 86 | .. note:: |
| 87 | |
| 88 | In this documentation, some methods are documented as coroutines, |
| 89 | even if they are plain Python functions returning a :class:`Future`. |
| 90 | This is intentional to have a freedom of tweaking the implementation |
| 91 | of these functions in the future. If such a function is needed to be |
Yury Selivanov | 04356e1 | 2015-06-30 22:13:22 -0400 | [diff] [blame] | 92 | used in a callback-style code, wrap its result with :func:`ensure_future`. |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 93 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 94 | |
Elvis Pranskevichus | 63536bd | 2018-05-19 23:15:06 -0400 | [diff] [blame] | 95 | .. function:: run(coro, \*, debug=False) |
Yury Selivanov | 02a0a19 | 2017-12-14 09:42:21 -0500 | [diff] [blame] | 96 | |
| 97 | This function runs the passed coroutine, taking care of |
| 98 | managing the asyncio event loop and finalizing asynchronous |
| 99 | generators. |
| 100 | |
| 101 | This function cannot be called when another asyncio event loop is |
| 102 | running in the same thread. |
| 103 | |
| 104 | If debug is True, the event loop will be run in debug mode. |
| 105 | |
| 106 | This function always creates a new event loop and closes it at |
| 107 | the end. It should be used as a main entry point for asyncio |
| 108 | programs, and should ideally only be called once. |
| 109 | |
| 110 | .. versionadded:: 3.7 |
Yury Selivanov | d8d715f | 2018-05-17 13:44:00 -0400 | [diff] [blame] | 111 | **Important:** this has been been added to asyncio in Python 3.7 |
| 112 | on a :term:`provisional basis <provisional api>`. |
Yury Selivanov | 02a0a19 | 2017-12-14 09:42:21 -0500 | [diff] [blame] | 113 | |
| 114 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 115 | .. _asyncio-hello-world-coroutine: |
| 116 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 117 | Example: Hello World coroutine |
| 118 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 119 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 120 | Example of coroutine displaying ``"Hello World"``:: |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 121 | |
| 122 | import asyncio |
| 123 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 124 | async def hello_world(): |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 125 | print("Hello World!") |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 126 | |
Yury Selivanov | 02a0a19 | 2017-12-14 09:42:21 -0500 | [diff] [blame] | 127 | asyncio.run(hello_world()) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 128 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 129 | .. seealso:: |
| 130 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 131 | The :ref:`Hello World with call_soon() <asyncio-hello-world-callback>` |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 132 | example uses the :meth:`AbstractEventLoop.call_soon` method to schedule a |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 133 | callback. |
| 134 | |
| 135 | |
| 136 | .. _asyncio-date-coroutine: |
| 137 | |
| 138 | Example: Coroutine displaying the current date |
| 139 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 140 | |
| 141 | Example of coroutine displaying the current date every second during 5 seconds |
| 142 | using the :meth:`sleep` function:: |
| 143 | |
| 144 | import asyncio |
| 145 | import datetime |
| 146 | |
Yury Selivanov | 02a0a19 | 2017-12-14 09:42:21 -0500 | [diff] [blame] | 147 | async def display_date(): |
| 148 | loop = asyncio.get_running_loop() |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 149 | end_time = loop.time() + 5.0 |
| 150 | while True: |
| 151 | print(datetime.datetime.now()) |
| 152 | if (loop.time() + 1.0) >= end_time: |
| 153 | break |
| 154 | await asyncio.sleep(1) |
| 155 | |
Yury Selivanov | 02a0a19 | 2017-12-14 09:42:21 -0500 | [diff] [blame] | 156 | asyncio.run(display_date()) |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 157 | |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 158 | .. seealso:: |
| 159 | |
| 160 | The :ref:`display the current date with call_later() |
| 161 | <asyncio-date-callback>` example uses a callback with the |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 162 | :meth:`AbstractEventLoop.call_later` method. |
Victor Stinner | 7f314ed | 2014-10-15 18:49:16 +0200 | [diff] [blame] | 163 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 164 | |
| 165 | Example: Chain coroutines |
| 166 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 167 | |
| 168 | Example chaining coroutines:: |
| 169 | |
| 170 | import asyncio |
| 171 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 172 | async def compute(x, y): |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 173 | print("Compute %s + %s ..." % (x, y)) |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 174 | await asyncio.sleep(1.0) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 175 | return x + y |
| 176 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 177 | async def print_sum(x, y): |
| 178 | result = await compute(x, y) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 179 | print("%s + %s = %s" % (x, y, result)) |
| 180 | |
| 181 | loop = asyncio.get_event_loop() |
| 182 | loop.run_until_complete(print_sum(1, 2)) |
Victor Stinner | f40c663 | 2014-01-28 23:32:40 +0100 | [diff] [blame] | 183 | loop.close() |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 184 | |
| 185 | ``compute()`` is chained to ``print_sum()``: ``print_sum()`` coroutine waits |
Brian Curtin | a1afeec | 2014-02-08 18:36:14 -0600 | [diff] [blame] | 186 | until ``compute()`` is completed before returning its result. |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 187 | |
Victor Stinner | 1c4b892 | 2013-12-12 12:35:17 +0100 | [diff] [blame] | 188 | Sequence diagram of the example: |
| 189 | |
| 190 | .. image:: tulip_coro.png |
| 191 | :align: center |
| 192 | |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 193 | The "Task" is created by the :meth:`AbstractEventLoop.run_until_complete` method |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 194 | when it gets a coroutine object instead of a task. |
Victor Stinner | 86e139a | 2013-12-13 12:51:24 +0100 | [diff] [blame] | 195 | |
| 196 | The diagram shows the control flow, it does not describe exactly how things |
| 197 | work internally. For example, the sleep coroutine creates an internal future |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 198 | which uses :meth:`AbstractEventLoop.call_later` to wake up the task in 1 second. |
Victor Stinner | 1c4b892 | 2013-12-12 12:35:17 +0100 | [diff] [blame] | 199 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 200 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 201 | InvalidStateError |
| 202 | ----------------- |
| 203 | |
| 204 | .. exception:: InvalidStateError |
| 205 | |
| 206 | The operation is not allowed in this state. |
| 207 | |
| 208 | |
Victor Stinner | 28d0ae48 | 2014-05-29 00:04:57 +0200 | [diff] [blame] | 209 | TimeoutError |
| 210 | ------------ |
| 211 | |
| 212 | .. exception:: TimeoutError |
| 213 | |
| 214 | The operation exceeded the given deadline. |
| 215 | |
| 216 | .. note:: |
| 217 | |
| 218 | This exception is different from the builtin :exc:`TimeoutError` exception! |
| 219 | |
| 220 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 221 | Future |
| 222 | ------ |
| 223 | |
| 224 | .. class:: Future(\*, loop=None) |
| 225 | |
| 226 | This class is *almost* compatible with :class:`concurrent.futures.Future`. |
| 227 | |
| 228 | Differences: |
| 229 | |
| 230 | - :meth:`result` and :meth:`exception` do not take a timeout argument and |
| 231 | raise an exception when the future isn't done yet. |
| 232 | |
| 233 | - Callbacks registered with :meth:`add_done_callback` are always called |
Antoine Pitrou | 22b1128 | 2017-11-07 17:03:28 +0100 | [diff] [blame] | 234 | via the event loop's :meth:`~AbstractEventLoop.call_soon`. |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 235 | |
| 236 | - This class is not compatible with the :func:`~concurrent.futures.wait` and |
| 237 | :func:`~concurrent.futures.as_completed` functions in the |
| 238 | :mod:`concurrent.futures` package. |
| 239 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 240 | This class is :ref:`not thread safe <asyncio-multithreading>`. |
| 241 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 242 | .. method:: cancel() |
| 243 | |
| 244 | Cancel the future and schedule callbacks. |
| 245 | |
| 246 | If the future is already done or cancelled, return ``False``. Otherwise, |
| 247 | change the future's state to cancelled, schedule the callbacks and return |
| 248 | ``True``. |
| 249 | |
| 250 | .. method:: cancelled() |
| 251 | |
| 252 | Return ``True`` if the future was cancelled. |
| 253 | |
| 254 | .. method:: done() |
| 255 | |
Serhiy Storchaka | 4adf01c | 2016-10-19 18:30:05 +0300 | [diff] [blame] | 256 | Return ``True`` if the future is done. |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 257 | |
| 258 | Done means either that a result / exception are available, or that the |
| 259 | future was cancelled. |
| 260 | |
| 261 | .. method:: result() |
| 262 | |
| 263 | Return the result this future represents. |
| 264 | |
| 265 | If the future has been cancelled, raises :exc:`CancelledError`. If the |
| 266 | future's result isn't yet available, raises :exc:`InvalidStateError`. If |
| 267 | the future is done and has an exception set, this exception is raised. |
| 268 | |
| 269 | .. method:: exception() |
| 270 | |
| 271 | Return the exception that was set on this future. |
| 272 | |
| 273 | The exception (or ``None`` if no exception was set) is returned only if |
| 274 | the future is done. If the future has been cancelled, raises |
| 275 | :exc:`CancelledError`. If the future isn't done yet, raises |
| 276 | :exc:`InvalidStateError`. |
| 277 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 278 | .. method:: add_done_callback(callback, *, context=None) |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 279 | |
| 280 | Add a callback to be run when the future becomes done. |
| 281 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 282 | The *callback* is called with a single argument - the future object. If the |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 283 | future is already done when this is called, the callback is scheduled |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 284 | with :meth:`~AbstractEventLoop.call_soon`. |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 285 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 286 | An optional keyword-only *context* argument allows specifying a custom |
| 287 | :class:`contextvars.Context` for the *callback* to run in. The current |
| 288 | context is used when no *context* is provided. |
| 289 | |
Victor Stinner | 8464c24 | 2014-11-28 13:15:41 +0100 | [diff] [blame] | 290 | :ref:`Use functools.partial to pass parameters to the callback |
| 291 | <asyncio-pass-keywords>`. For example, |
| 292 | ``fut.add_done_callback(functools.partial(print, "Future:", |
| 293 | flush=True))`` will call ``print("Future:", fut, flush=True)``. |
| 294 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 295 | .. versionchanged:: 3.7 |
| 296 | The *context* keyword-only parameter was added. See :pep:`567` |
| 297 | for more details. |
| 298 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 299 | .. method:: remove_done_callback(fn) |
| 300 | |
| 301 | Remove all instances of a callback from the "call when done" list. |
| 302 | |
| 303 | Returns the number of callbacks removed. |
| 304 | |
| 305 | .. method:: set_result(result) |
| 306 | |
| 307 | Mark the future done and set its result. |
| 308 | |
| 309 | If the future is already done when this method is called, raises |
| 310 | :exc:`InvalidStateError`. |
| 311 | |
| 312 | .. method:: set_exception(exception) |
| 313 | |
| 314 | Mark the future done and set an exception. |
| 315 | |
| 316 | If the future is already done when this method is called, raises |
| 317 | :exc:`InvalidStateError`. |
| 318 | |
Yury Selivanov | ca9b36c | 2017-12-23 15:04:15 -0500 | [diff] [blame] | 319 | .. method:: get_loop() |
| 320 | |
| 321 | Return the event loop the future object is bound to. |
| 322 | |
| 323 | .. versionadded:: 3.7 |
| 324 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 325 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 326 | Example: Future with run_until_complete() |
| 327 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 328 | |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 329 | Example combining a :class:`Future` and a :ref:`coroutine function |
| 330 | <coroutine>`:: |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 331 | |
| 332 | import asyncio |
| 333 | |
Berker Peksag | f592867 | 2017-02-07 11:27:09 +0300 | [diff] [blame] | 334 | async def slow_operation(future): |
| 335 | await asyncio.sleep(1) |
Victor Stinner | 04e05da | 2014-02-17 10:54:30 +0100 | [diff] [blame] | 336 | future.set_result('Future is done!') |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 337 | |
| 338 | loop = asyncio.get_event_loop() |
| 339 | future = asyncio.Future() |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 340 | asyncio.ensure_future(slow_operation(future)) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 341 | loop.run_until_complete(future) |
| 342 | print(future.result()) |
Victor Stinner | f40c663 | 2014-01-28 23:32:40 +0100 | [diff] [blame] | 343 | loop.close() |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 344 | |
Terry Jan Reedy | c935a95 | 2014-07-24 02:33:14 -0400 | [diff] [blame] | 345 | The coroutine function is responsible for the computation (which takes 1 second) |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 346 | and it stores the result into the future. The |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 347 | :meth:`~AbstractEventLoop.run_until_complete` method waits for the completion of |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 348 | the future. |
| 349 | |
| 350 | .. note:: |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 351 | The :meth:`~AbstractEventLoop.run_until_complete` method uses internally the |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 352 | :meth:`~Future.add_done_callback` method to be notified when the future is |
| 353 | done. |
| 354 | |
| 355 | |
| 356 | Example: Future with run_forever() |
| 357 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 358 | |
| 359 | The previous example can be written differently using the |
| 360 | :meth:`Future.add_done_callback` method to describe explicitly the control |
| 361 | flow:: |
| 362 | |
| 363 | import asyncio |
| 364 | |
Berker Peksag | f592867 | 2017-02-07 11:27:09 +0300 | [diff] [blame] | 365 | async def slow_operation(future): |
| 366 | await asyncio.sleep(1) |
Victor Stinner | 04e05da | 2014-02-17 10:54:30 +0100 | [diff] [blame] | 367 | future.set_result('Future is done!') |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 368 | |
| 369 | def got_result(future): |
| 370 | print(future.result()) |
| 371 | loop.stop() |
| 372 | |
| 373 | loop = asyncio.get_event_loop() |
| 374 | future = asyncio.Future() |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 375 | asyncio.ensure_future(slow_operation(future)) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 376 | future.add_done_callback(got_result) |
Victor Stinner | 04e05da | 2014-02-17 10:54:30 +0100 | [diff] [blame] | 377 | try: |
| 378 | loop.run_forever() |
| 379 | finally: |
| 380 | loop.close() |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 381 | |
Victor Stinner | 039f703 | 2014-12-02 17:52:45 +0100 | [diff] [blame] | 382 | In this example, the future is used to link ``slow_operation()`` to |
| 383 | ``got_result()``: when ``slow_operation()`` is done, ``got_result()`` is called |
| 384 | with the result. |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 385 | |
| 386 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 387 | Task |
| 388 | ---- |
| 389 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 390 | .. function:: create_task(coro, \*, name=None) |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 391 | |
| 392 | Wrap a :ref:`coroutine <coroutine>` *coro* into a task and schedule |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 393 | its execution. Return the task object. |
| 394 | |
| 395 | If *name* is not ``None``, it is set as the name of the task using |
| 396 | :meth:`Task.set_name`. |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 397 | |
| 398 | The task is executed in :func:`get_running_loop` context, |
| 399 | :exc:`RuntimeError` is raised if there is no running loop in |
| 400 | current thread. |
| 401 | |
| 402 | .. versionadded:: 3.7 |
| 403 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 404 | .. versionchanged:: 3.8 |
| 405 | Added the ``name`` parameter. |
| 406 | |
| 407 | .. class:: Task(coro, \*, loop=None, name=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 408 | |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 409 | A unit for concurrent running of :ref:`coroutines <coroutine>`, |
| 410 | subclass of :class:`Future`. |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 411 | |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 412 | A task is responsible for executing a coroutine object in an event loop. If |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 413 | the wrapped coroutine yields from a future, the task suspends the execution |
Berker Peksag | 002b0a7 | 2016-10-04 20:45:47 +0300 | [diff] [blame] | 414 | of the wrapped coroutine and waits for the completion of the future. When |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 415 | the future is done, the execution of the wrapped coroutine restarts with the |
| 416 | result or the exception of the future. |
| 417 | |
| 418 | Event loops use cooperative scheduling: an event loop only runs one task at |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 419 | a time. Other tasks may run in parallel if other event loops are |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 420 | running in different threads. While a task waits for the completion of a |
| 421 | future, the event loop executes a new task. |
| 422 | |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 423 | The cancellation of a task is different from the cancellation of a |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 424 | future. Calling :meth:`cancel` will throw a |
| 425 | :exc:`~concurrent.futures.CancelledError` to the wrapped |
| 426 | coroutine. :meth:`~Future.cancelled` only returns ``True`` if the |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 427 | wrapped coroutine did not catch the |
| 428 | :exc:`~concurrent.futures.CancelledError` exception, or raised a |
| 429 | :exc:`~concurrent.futures.CancelledError` exception. |
| 430 | |
| 431 | If a pending task is destroyed, the execution of its wrapped :ref:`coroutine |
| 432 | <coroutine>` did not complete. It is probably a bug and a warning is |
| 433 | logged: see :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`. |
| 434 | |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 435 | Don't directly create :class:`Task` instances: use the :func:`create_task` |
Guido van Rossum | f68afd8 | 2016-08-08 09:41:21 -0700 | [diff] [blame] | 436 | function or the :meth:`AbstractEventLoop.create_task` method. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 437 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 438 | Tasks support the :mod:`contextvars` module. When a Task |
| 439 | is created it copies the current context and later runs its coroutine |
| 440 | in the copied context. See :pep:`567` for more details. |
| 441 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 442 | This class is :ref:`not thread safe <asyncio-multithreading>`. |
| 443 | |
Yury Selivanov | 28b9178 | 2018-05-23 13:35:04 -0400 | [diff] [blame] | 444 | .. versionchanged:: 3.7 |
| 445 | Added support for the :mod:`contextvars` module. |
| 446 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 447 | .. versionchanged:: 3.8 |
| 448 | Added the ``name`` parameter. |
| 449 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 450 | .. classmethod:: all_tasks(loop=None) |
| 451 | |
| 452 | Return a set of all tasks for an event loop. |
| 453 | |
| 454 | By default all tasks for the current event loop are returned. |
Yury Selivanov | 416c1eb | 2018-05-28 17:54:02 -0400 | [diff] [blame] | 455 | If *loop* is ``None``, :func:`get_event_loop` function |
| 456 | is used to get the current loop. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 457 | |
Victor Stinner | 742520b | 2013-12-10 12:14:50 +0100 | [diff] [blame] | 458 | .. classmethod:: current_task(loop=None) |
| 459 | |
| 460 | Return the currently running task in an event loop or ``None``. |
| 461 | |
| 462 | By default the current task for the current event loop is returned. |
| 463 | |
| 464 | ``None`` is returned when called not in the context of a :class:`Task`. |
| 465 | |
Victor Stinner | 8d21357 | 2014-06-02 23:06:46 +0200 | [diff] [blame] | 466 | .. method:: cancel() |
| 467 | |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 468 | Request that this task cancel itself. |
Victor Stinner | 8d21357 | 2014-06-02 23:06:46 +0200 | [diff] [blame] | 469 | |
| 470 | This arranges for a :exc:`~concurrent.futures.CancelledError` to be |
| 471 | thrown into the wrapped coroutine on the next cycle through the event |
| 472 | loop. The coroutine then has a chance to clean up or even deny the |
| 473 | request using try/except/finally. |
| 474 | |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 475 | Unlike :meth:`Future.cancel`, this does not guarantee that the task |
Victor Stinner | 8d21357 | 2014-06-02 23:06:46 +0200 | [diff] [blame] | 476 | will be cancelled: the exception might be caught and acted upon, delaying |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 477 | cancellation of the task or preventing cancellation completely. The task |
| 478 | may also return a value or raise a different exception. |
Victor Stinner | 8d21357 | 2014-06-02 23:06:46 +0200 | [diff] [blame] | 479 | |
| 480 | Immediately after this method is called, :meth:`~Future.cancelled` will |
| 481 | not return ``True`` (unless the task was already cancelled). A task will |
| 482 | be marked as cancelled when the wrapped coroutine terminates with a |
| 483 | :exc:`~concurrent.futures.CancelledError` exception (even if |
| 484 | :meth:`cancel` was not called). |
| 485 | |
| 486 | .. method:: get_stack(\*, limit=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 487 | |
| 488 | Return the list of stack frames for this task's coroutine. |
| 489 | |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 490 | If the coroutine is not done, this returns the stack where it is |
| 491 | suspended. If the coroutine has completed successfully or was |
| 492 | cancelled, this returns an empty list. If the coroutine was |
| 493 | terminated by an exception, this returns the list of traceback |
| 494 | frames. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 495 | |
| 496 | The frames are always ordered from oldest to newest. |
| 497 | |
Brian Curtin | a1afeec | 2014-02-08 18:36:14 -0600 | [diff] [blame] | 498 | The optional limit gives the maximum number of frames to return; by |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 499 | default all available frames are returned. Its meaning differs depending |
| 500 | on whether a stack or a traceback is returned: the newest frames of a |
| 501 | stack are returned, but the oldest frames of a traceback are returned. |
| 502 | (This matches the behavior of the traceback module.) |
| 503 | |
| 504 | For reasons beyond our control, only one stack frame is returned for a |
| 505 | suspended coroutine. |
| 506 | |
| 507 | .. method:: print_stack(\*, limit=None, file=None) |
| 508 | |
| 509 | Print the stack or traceback for this task's coroutine. |
| 510 | |
| 511 | This produces output similar to that of the traceback module, for the |
| 512 | frames retrieved by get_stack(). The limit argument is passed to |
| 513 | get_stack(). The file argument is an I/O stream to which the output |
R David Murray | 22dd833 | 2014-09-24 11:09:09 -0400 | [diff] [blame] | 514 | is written; by default output is written to sys.stderr. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 515 | |
Alex Grönholm | cca4eec | 2018-08-09 00:06:47 +0300 | [diff] [blame] | 516 | .. method:: get_name() |
| 517 | |
| 518 | Return the name of the task. |
| 519 | |
| 520 | If no name has been explicitly assigned to the task, the default |
| 521 | ``Task`` implementation generates a default name during instantiation. |
| 522 | |
| 523 | .. versionadded:: 3.8 |
| 524 | |
| 525 | .. method:: set_name(value) |
| 526 | |
| 527 | Set the name of the task. |
| 528 | |
| 529 | The *value* argument can be any object, which is then converted to a |
| 530 | string. |
| 531 | |
| 532 | In the default ``Task`` implementation, the name will be visible in the |
| 533 | :func:`repr` output of a task object. |
| 534 | |
| 535 | .. versionadded:: 3.8 |
| 536 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 537 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 538 | Example: Parallel execution of tasks |
| 539 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 540 | |
| 541 | Example executing 3 tasks (A, B, C) in parallel:: |
| 542 | |
| 543 | import asyncio |
| 544 | |
Berker Peksag | d5adb63 | 2017-02-01 22:37:16 +0300 | [diff] [blame] | 545 | async def factorial(name, number): |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 546 | f = 1 |
Victor Stinner | 34f2946 | 2013-12-10 02:51:05 +0100 | [diff] [blame] | 547 | for i in range(2, number+1): |
| 548 | print("Task %s: Compute factorial(%s)..." % (name, i)) |
Berker Peksag | d5adb63 | 2017-02-01 22:37:16 +0300 | [diff] [blame] | 549 | await asyncio.sleep(1) |
Victor Stinner | 34f2946 | 2013-12-10 02:51:05 +0100 | [diff] [blame] | 550 | f *= i |
| 551 | print("Task %s: factorial(%s) = %s" % (name, number, f)) |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 552 | |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 553 | loop = asyncio.get_event_loop() |
Berker Peksag | d5adb63 | 2017-02-01 22:37:16 +0300 | [diff] [blame] | 554 | loop.run_until_complete(asyncio.gather( |
| 555 | factorial("A", 2), |
| 556 | factorial("B", 3), |
| 557 | factorial("C", 4), |
| 558 | )) |
Victor Stinner | f40c663 | 2014-01-28 23:32:40 +0100 | [diff] [blame] | 559 | loop.close() |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 560 | |
| 561 | Output:: |
| 562 | |
Victor Stinner | 34f2946 | 2013-12-10 02:51:05 +0100 | [diff] [blame] | 563 | Task A: Compute factorial(2)... |
| 564 | Task B: Compute factorial(2)... |
| 565 | Task C: Compute factorial(2)... |
| 566 | Task A: factorial(2) = 2 |
| 567 | Task B: Compute factorial(3)... |
| 568 | Task C: Compute factorial(3)... |
| 569 | Task B: factorial(3) = 6 |
| 570 | Task C: Compute factorial(4)... |
| 571 | Task C: factorial(4) = 24 |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 572 | |
Victor Stinner | 34f2946 | 2013-12-10 02:51:05 +0100 | [diff] [blame] | 573 | A task is automatically scheduled for execution when it is created. The event |
Victor Stinner | b69d62d | 2013-12-10 02:09:46 +0100 | [diff] [blame] | 574 | loop stops when all tasks are done. |
| 575 | |
| 576 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 577 | Task functions |
| 578 | -------------- |
| 579 | |
Eli Bendersky | 029981b | 2014-01-20 07:02:22 -0800 | [diff] [blame] | 580 | .. note:: |
| 581 | |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 582 | In the functions below, the optional *loop* argument allows explicitly setting |
Eli Bendersky | 029981b | 2014-01-20 07:02:22 -0800 | [diff] [blame] | 583 | the event loop object used by the underlying task or coroutine. If it's |
| 584 | not provided, the default event loop is used. |
| 585 | |
Andrew Svetlov | 44d1a59 | 2017-12-16 21:58:38 +0200 | [diff] [blame] | 586 | |
Andrew Svetlov | b21505e | 2018-03-12 20:50:50 +0200 | [diff] [blame] | 587 | .. function:: current_task(loop=None) |
Andrew Svetlov | 44d1a59 | 2017-12-16 21:58:38 +0200 | [diff] [blame] | 588 | |
| 589 | Return the current running :class:`Task` instance or ``None``, if |
| 590 | no task is running. |
| 591 | |
| 592 | If *loop* is ``None`` :func:`get_running_loop` is used to get |
| 593 | the current loop. |
| 594 | |
| 595 | .. versionadded:: 3.7 |
| 596 | |
| 597 | |
Andrew Svetlov | b21505e | 2018-03-12 20:50:50 +0200 | [diff] [blame] | 598 | .. function:: all_tasks(loop=None) |
Andrew Svetlov | 44d1a59 | 2017-12-16 21:58:38 +0200 | [diff] [blame] | 599 | |
| 600 | Return a set of :class:`Task` objects created for the loop. |
| 601 | |
Yury Selivanov | 416c1eb | 2018-05-28 17:54:02 -0400 | [diff] [blame] | 602 | If *loop* is ``None``, :func:`get_running_loop` is used for getting |
| 603 | current loop (contrary to the deprecated :meth:`Task.all_tasks` method |
| 604 | that uses :func:`get_event_loop`.) |
Andrew Svetlov | 44d1a59 | 2017-12-16 21:58:38 +0200 | [diff] [blame] | 605 | |
| 606 | .. versionadded:: 3.7 |
| 607 | |
| 608 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 609 | .. function:: as_completed(fs, \*, loop=None, timeout=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 610 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 611 | Return an iterator whose values, when waited for, are :class:`Future` |
| 612 | instances. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 613 | |
Victor Stinner | 28d0ae48 | 2014-05-29 00:04:57 +0200 | [diff] [blame] | 614 | Raises :exc:`asyncio.TimeoutError` if the timeout occurs before all Futures |
| 615 | are done. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 616 | |
| 617 | Example:: |
| 618 | |
| 619 | for f in as_completed(fs): |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 620 | result = await f # The 'await' may raise |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 621 | # Use result |
| 622 | |
| 623 | .. note:: |
| 624 | |
| 625 | The futures ``f`` are not necessarily members of fs. |
| 626 | |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 627 | .. function:: ensure_future(coro_or_future, \*, loop=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 628 | |
Victor Stinner | 980dd84 | 2014-10-12 21:36:17 +0200 | [diff] [blame] | 629 | Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in |
| 630 | a future. Return a :class:`Task` object. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 631 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 632 | If the argument is a :class:`Future`, it is returned directly. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 633 | |
Yury Selivanov | d7e19bb | 2015-05-11 16:33:41 -0400 | [diff] [blame] | 634 | .. versionadded:: 3.4.4 |
| 635 | |
Yury Selivanov | e319ab0 | 2015-12-15 00:45:24 -0500 | [diff] [blame] | 636 | .. versionchanged:: 3.5.1 |
| 637 | The function accepts any :term:`awaitable` object. |
| 638 | |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 639 | .. note:: |
| 640 | |
| 641 | :func:`create_task` (added in Python 3.7) is the preferable way |
| 642 | for spawning new tasks. |
| 643 | |
Victor Stinner | 337e03f | 2014-08-11 01:11:13 +0200 | [diff] [blame] | 644 | .. seealso:: |
| 645 | |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame] | 646 | The :func:`create_task` function and |
| 647 | :meth:`AbstractEventLoop.create_task` method. |
Victor Stinner | 337e03f | 2014-08-11 01:11:13 +0200 | [diff] [blame] | 648 | |
adisbladis | 824f687 | 2017-06-09 14:28:59 +0800 | [diff] [blame] | 649 | .. function:: wrap_future(future, \*, loop=None) |
| 650 | |
| 651 | Wrap a :class:`concurrent.futures.Future` object in a :class:`Future` |
| 652 | object. |
| 653 | |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 654 | .. function:: gather(\*coros_or_futures, loop=None, return_exceptions=False) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 655 | |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 656 | Return a future aggregating results from the given coroutine objects or |
| 657 | futures. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 658 | |
| 659 | All futures must share the same event loop. If all the tasks are done |
| 660 | successfully, the returned future's result is the list of results (in the |
| 661 | order of the original sequence, not necessarily the order of results |
Serhiy Storchaka | 4adf01c | 2016-10-19 18:30:05 +0300 | [diff] [blame] | 662 | arrival). If *return_exceptions* is true, exceptions in the tasks are |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 663 | treated the same as successful results, and gathered in the result list; |
| 664 | otherwise, the first raised exception will be immediately propagated to the |
| 665 | returned future. |
| 666 | |
| 667 | Cancellation: if the outer Future is cancelled, all children (that have not |
| 668 | completed yet) are also cancelled. If any child is cancelled, this is |
| 669 | treated as if it raised :exc:`~concurrent.futures.CancelledError` -- the |
| 670 | outer Future is *not* cancelled in this case. (This is to prevent the |
| 671 | cancellation of one child to cause other children to be cancelled.) |
| 672 | |
Yury Selivanov | 863b674 | 2018-05-29 17:20:02 -0400 | [diff] [blame] | 673 | .. versionchanged:: 3.7.0 |
| 674 | If the *gather* itself is cancelled, the cancellation is propagated |
| 675 | regardless of *return_exceptions*. |
| 676 | |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 677 | .. function:: iscoroutine(obj) |
| 678 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 679 | Return ``True`` if *obj* is a :ref:`coroutine object <coroutine>`, |
| 680 | which may be based on a generator or an :keyword:`async def` coroutine. |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 681 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 682 | .. function:: iscoroutinefunction(func) |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 683 | |
Yury Selivanov | 66f8828 | 2015-06-24 11:04:15 -0400 | [diff] [blame] | 684 | Return ``True`` if *func* is determined to be a :ref:`coroutine function |
| 685 | <coroutine>`, which may be a decorated generator function or an |
| 686 | :keyword:`async def` function. |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 687 | |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 688 | .. function:: run_coroutine_threadsafe(coro, loop) |
| 689 | |
| 690 | Submit a :ref:`coroutine object <coroutine>` to a given event loop. |
| 691 | |
| 692 | Return a :class:`concurrent.futures.Future` to access the result. |
| 693 | |
| 694 | This function is meant to be called from a different thread than the one |
| 695 | where the event loop is running. Usage:: |
| 696 | |
| 697 | # Create a coroutine |
| 698 | coro = asyncio.sleep(1, result=3) |
| 699 | # Submit the coroutine to a given loop |
| 700 | future = asyncio.run_coroutine_threadsafe(coro, loop) |
| 701 | # Wait for the result with an optional timeout argument |
| 702 | assert future.result(timeout) == 3 |
| 703 | |
| 704 | If an exception is raised in the coroutine, the returned future will be |
| 705 | notified. It can also be used to cancel the task in the event loop:: |
| 706 | |
| 707 | try: |
| 708 | result = future.result(timeout) |
| 709 | except asyncio.TimeoutError: |
| 710 | print('The coroutine took too long, cancelling the task...') |
| 711 | future.cancel() |
| 712 | except Exception as exc: |
| 713 | print('The coroutine raised an exception: {!r}'.format(exc)) |
| 714 | else: |
| 715 | print('The coroutine returned: {!r}'.format(result)) |
| 716 | |
| 717 | See the :ref:`concurrency and multithreading <asyncio-multithreading>` |
| 718 | section of the documentation. |
| 719 | |
| 720 | .. note:: |
| 721 | |
Andrew Svetlov | 3af81f2 | 2016-01-11 14:45:25 +0200 | [diff] [blame] | 722 | Unlike other functions from the module, |
| 723 | :func:`run_coroutine_threadsafe` requires the *loop* argument to |
Zachary Ware | f9aff92 | 2016-06-01 00:01:10 -0500 | [diff] [blame] | 724 | be passed explicitly. |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 725 | |
Andrew Svetlov | ea47134 | 2016-01-11 15:41:43 +0200 | [diff] [blame] | 726 | .. versionadded:: 3.5.1 |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 727 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 728 | .. coroutinefunction:: sleep(delay, result=None, \*, loop=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 729 | |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 730 | Create a :ref:`coroutine <coroutine>` that completes after a given |
Eli Bendersky | 2d26af8 | 2014-01-20 06:59:23 -0800 | [diff] [blame] | 731 | time (in seconds). If *result* is provided, it is produced to the caller |
| 732 | when the coroutine completes. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 733 | |
Victor Stinner | 45b27ed | 2014-02-01 02:36:43 +0100 | [diff] [blame] | 734 | The resolution of the sleep depends on the :ref:`granularity of the event |
| 735 | loop <asyncio-delayed-calls>`. |
| 736 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 737 | This function is a :ref:`coroutine <coroutine>`. |
| 738 | |
Joongi Kim | 13cfd57 | 2018-03-04 01:43:54 +0900 | [diff] [blame] | 739 | .. coroutinefunction:: shield(arg, \*, loop=None) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 740 | |
| 741 | Wait for a future, shielding it from cancellation. |
| 742 | |
| 743 | The statement:: |
| 744 | |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 745 | res = await shield(something()) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 746 | |
| 747 | is exactly equivalent to the statement:: |
| 748 | |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 749 | res = await something() |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 750 | |
| 751 | *except* that if the coroutine containing it is cancelled, the task running |
| 752 | in ``something()`` is not cancelled. From the point of view of |
| 753 | ``something()``, the cancellation did not happen. But its caller is still |
| 754 | cancelled, so the yield-from expression still raises |
| 755 | :exc:`~concurrent.futures.CancelledError`. Note: If ``something()`` is |
| 756 | cancelled by other means this will still cancel ``shield()``. |
| 757 | |
| 758 | If you want to completely ignore cancellation (not recommended) you can |
| 759 | combine ``shield()`` with a try/except clause, as follows:: |
| 760 | |
| 761 | try: |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 762 | res = await shield(something()) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 763 | except CancelledError: |
| 764 | res = None |
| 765 | |
Yury Selivanov | 950204d | 2016-05-16 16:23:00 -0400 | [diff] [blame] | 766 | |
Andrew Svetlov | f124016 | 2016-01-11 14:40:35 +0200 | [diff] [blame] | 767 | .. coroutinefunction:: wait(futures, \*, loop=None, timeout=None,\ |
| 768 | return_when=ALL_COMPLETED) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 769 | |
Victor Stinner | 59759ff | 2014-01-16 19:30:21 +0100 | [diff] [blame] | 770 | Wait for the Futures and coroutine objects given by the sequence *futures* |
| 771 | to complete. Coroutines will be wrapped in Tasks. Returns two sets of |
Victor Stinner | 99c2ab4 | 2013-12-03 19:17:25 +0100 | [diff] [blame] | 772 | :class:`Future`: (done, pending). |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 773 | |
Victor Stinner | db74d98 | 2014-06-10 11:16:05 +0200 | [diff] [blame] | 774 | The sequence *futures* must not be empty. |
| 775 | |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 776 | *timeout* can be used to control the maximum number of seconds to wait before |
| 777 | returning. *timeout* can be an int or float. If *timeout* is not specified |
| 778 | or ``None``, there is no limit to the wait time. |
| 779 | |
| 780 | *return_when* indicates when this function should return. It must be one of |
Victor Stinner | 933a8c8 | 2013-12-03 01:59:38 +0100 | [diff] [blame] | 781 | the following constants of the :mod:`concurrent.futures` module: |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 782 | |
| 783 | .. tabularcolumns:: |l|L| |
| 784 | |
| 785 | +-----------------------------+----------------------------------------+ |
| 786 | | Constant | Description | |
| 787 | +=============================+========================================+ |
| 788 | | :const:`FIRST_COMPLETED` | The function will return when any | |
| 789 | | | future finishes or is cancelled. | |
| 790 | +-----------------------------+----------------------------------------+ |
| 791 | | :const:`FIRST_EXCEPTION` | The function will return when any | |
| 792 | | | future finishes by raising an | |
| 793 | | | exception. If no future raises an | |
| 794 | | | exception then it is equivalent to | |
| 795 | | | :const:`ALL_COMPLETED`. | |
| 796 | +-----------------------------+----------------------------------------+ |
| 797 | | :const:`ALL_COMPLETED` | The function will return when all | |
| 798 | | | futures finish or are cancelled. | |
| 799 | +-----------------------------+----------------------------------------+ |
| 800 | |
Elvis Pranskevichus | f9aeca2 | 2018-05-29 18:21:44 -0400 | [diff] [blame] | 801 | Unlike :func:`~asyncio.wait_for`, ``wait()`` will not cancel the futures |
Elvis Pranskevichus | dec947c | 2018-05-29 20:14:59 -0400 | [diff] [blame] | 802 | when a timeout occurs. |
Elvis Pranskevichus | f9aeca2 | 2018-05-29 18:21:44 -0400 | [diff] [blame] | 803 | |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 804 | This function is a :ref:`coroutine <coroutine>`. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 805 | |
| 806 | Usage:: |
| 807 | |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 808 | done, pending = await asyncio.wait(fs) |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 809 | |
| 810 | .. note:: |
| 811 | |
Victor Stinner | 28d0ae48 | 2014-05-29 00:04:57 +0200 | [diff] [blame] | 812 | This does not raise :exc:`asyncio.TimeoutError`! Futures that aren't done |
| 813 | when the timeout occurs are returned in the second set. |
Victor Stinner | ea3183f | 2013-12-03 01:08:00 +0100 | [diff] [blame] | 814 | |
Victor Stinner | 3e09e32 | 2013-12-03 01:22:06 +0100 | [diff] [blame] | 815 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 816 | .. coroutinefunction:: wait_for(fut, timeout, \*, loop=None) |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 817 | |
| 818 | Wait for the single :class:`Future` or :ref:`coroutine object <coroutine>` |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 819 | to complete with timeout. If *timeout* is ``None``, block until the future |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 820 | completes. |
| 821 | |
Victor Stinner | 337e03f | 2014-08-11 01:11:13 +0200 | [diff] [blame] | 822 | Coroutine will be wrapped in :class:`Task`. |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 823 | |
| 824 | Returns result of the Future or coroutine. When a timeout occurs, it |
Victor Stinner | 28d0ae48 | 2014-05-29 00:04:57 +0200 | [diff] [blame] | 825 | cancels the task and raises :exc:`asyncio.TimeoutError`. To avoid the task |
Elvis Pranskevichus | e2b340a | 2018-05-29 17:31:01 -0400 | [diff] [blame] | 826 | cancellation, wrap it in :func:`shield`. The function will wait until |
| 827 | the future is actually cancelled, so the total wait time may exceed |
| 828 | the *timeout*. |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 829 | |
Victor Stinner | 72dcb0a | 2015-04-03 17:08:19 +0200 | [diff] [blame] | 830 | If the wait is cancelled, the future *fut* is also cancelled. |
| 831 | |
Victor Stinner | 530ef2f | 2014-07-08 12:39:10 +0200 | [diff] [blame] | 832 | This function is a :ref:`coroutine <coroutine>`, usage:: |
Yury Selivanov | 37f15bc | 2014-02-20 16:20:44 -0500 | [diff] [blame] | 833 | |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 834 | result = await asyncio.wait_for(fut, 60.0) |
Victor Stinner | 1ad5afc | 2014-01-30 00:18:50 +0100 | [diff] [blame] | 835 | |
Victor Stinner | 72dcb0a | 2015-04-03 17:08:19 +0200 | [diff] [blame] | 836 | .. versionchanged:: 3.4.3 |
| 837 | If the wait is cancelled, the future *fut* is now also cancelled. |
Elvis Pranskevichus | e2b340a | 2018-05-29 17:31:01 -0400 | [diff] [blame] | 838 | |
| 839 | .. versionchanged:: 3.7 |
| 840 | When *fut* is cancelled due to a timeout, ``wait_for`` now waits |
| 841 | for *fut* to be cancelled. Previously, |
| 842 | it raised :exc:`~asyncio.TimeoutError` immediately. |