| 1 |
.. currentmodule:: asyncio |
| 2 |
|
| 3 |
.. _asyncio-dev: |
| 4 |
|
| 5 |
======================= |
| 6 |
Developing with asyncio |
| 7 |
======================= |
| 8 |
|
| 9 |
Asynchronous programming is different from classic "sequential" |
| 10 |
programming. |
| 11 |
|
| 12 |
This page lists common mistakes and traps and explains how |
| 13 |
to avoid them. |
| 14 |
|
| 15 |
|
| 16 |
.. _asyncio-debug-mode: |
| 17 |
|
| 18 |
Debug Mode |
| 19 |
========== |
| 20 |
|
| 21 |
By default asyncio runs in production mode. In order to ease |
| 22 |
the development asyncio has a *debug mode*. |
| 23 |
|
| 24 |
There are several ways to enable asyncio debug mode: |
| 25 |
|
| 26 |
* Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``. |
| 27 |
|
| 28 |
* Using the :ref:`Python Development Mode <devmode>`. |
| 29 |
|
| 30 |
* Passing ``debug=True`` to :func:`asyncio.run`. |
| 31 |
|
| 32 |
* Calling :meth:`loop.set_debug`. |
| 33 |
|
| 34 |
In addition to enabling the debug mode, consider also: |
| 35 |
|
| 36 |
* setting the log level of the :ref:`asyncio logger <asyncio-logger>` to |
| 37 |
:py:const:`logging.DEBUG`, for example the following snippet of code |
| 38 |
can be run at startup of the application:: |
| 39 |
|
| 40 |
logging.basicConfig(level=logging.DEBUG) |
| 41 |
|
| 42 |
* configuring the :mod:`warnings` module to display |
| 43 |
:exc:`ResourceWarning` warnings. One way of doing that is by |
| 44 |
using the :option:`-W` ``default`` command line option. |
| 45 |
|
| 46 |
|
| 47 |
When the debug mode is enabled: |
| 48 |
|
| 49 |
* Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and |
| 50 |
:meth:`loop.call_at` methods) raise an exception if they are called |
| 51 |
from a wrong thread. |
| 52 |
|
| 53 |
* The execution time of the I/O selector is logged if it takes too long to |
| 54 |
perform an I/O operation. |
| 55 |
|
| 56 |
* Callbacks taking longer than 100 milliseconds are logged. The |
| 57 |
:attr:`loop.slow_callback_duration` attribute can be used to set the |
| 58 |
minimum execution duration in seconds that is considered "slow". |
| 59 |
|
| 60 |
|
| 61 |
.. _asyncio-multithreading: |
| 62 |
|
| 63 |
Concurrency and Multithreading |
| 64 |
============================== |
| 65 |
|
| 66 |
An event loop runs in a thread (typically the main thread) and executes |
| 67 |
all callbacks and Tasks in its thread. While a Task is running in the |
| 68 |
event loop, no other Tasks can run in the same thread. When a Task |
| 69 |
executes an ``await`` expression, the running Task gets suspended, and |
| 70 |
the event loop executes the next Task. |
| 71 |
|
| 72 |
To schedule a :term:`callback` from another OS thread, the |
| 73 |
:meth:`loop.call_soon_threadsafe` method should be used. Example:: |
| 74 |
|
| 75 |
loop.call_soon_threadsafe(callback, *args) |
| 76 |
|
| 77 |
Almost all asyncio objects are not thread safe, which is typically |
| 78 |
not a problem unless there is code that works with them from outside |
| 79 |
of a Task or a callback. If there's a need for such code to call a |
| 80 |
low-level asyncio API, the :meth:`loop.call_soon_threadsafe` method |
| 81 |
should be used, e.g.:: |
| 82 |
|
| 83 |
loop.call_soon_threadsafe(fut.cancel) |
| 84 |
|
| 85 |
To schedule a coroutine object from a different OS thread, the |
| 86 |
:func:`run_coroutine_threadsafe` function should be used. It returns a |
| 87 |
:class:`concurrent.futures.Future` to access the result:: |
| 88 |
|
| 89 |
async def coro_func(): |
| 90 |
return await asyncio.sleep(1, 42) |
| 91 |
|
| 92 |
# Later in another OS thread: |
| 93 |
|
| 94 |
future = asyncio.run_coroutine_threadsafe(coro_func(), loop) |
| 95 |
# Wait for the result: |
| 96 |
result = future.result() |
| 97 |
|
| 98 |
To handle signals the event loop must be |
| 99 |
run in the main thread. |
| 100 |
|
| 101 |
The :meth:`loop.run_in_executor` method can be used with a |
| 102 |
:class:`concurrent.futures.ThreadPoolExecutor` or |
| 103 |
:class:`~concurrent.futures.InterpreterPoolExecutor` to execute |
| 104 |
blocking code in a different OS thread without blocking the OS thread |
| 105 |
that the event loop runs in. |
| 106 |
|
| 107 |
There is currently no way to schedule coroutines or callbacks directly |
| 108 |
from a different process (such as one started with |
| 109 |
:mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods` |
| 110 |
section lists APIs that can read from pipes and watch file descriptors |
| 111 |
without blocking the event loop. In addition, asyncio's |
| 112 |
:ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a |
| 113 |
process and communicate with it from the event loop. Lastly, the |
| 114 |
aforementioned :meth:`loop.run_in_executor` method can also be used |
| 115 |
with a :class:`concurrent.futures.ProcessPoolExecutor` to execute |
| 116 |
code in a different process. |
| 117 |
|
| 118 |
.. _asyncio-handle-blocking: |
| 119 |
|
| 120 |
Running Blocking Code |
| 121 |
===================== |
| 122 |
|
| 123 |
Blocking (CPU-bound) code should not be called directly. For example, |
| 124 |
if a function performs a CPU-intensive calculation for 1 second, |
| 125 |
all concurrent asyncio Tasks and IO operations would be delayed |
| 126 |
by 1 second. |
| 127 |
|
| 128 |
An executor can be used to run a task in a different thread, |
| 129 |
including in a different interpreter, or even in |
| 130 |
a different process to avoid blocking the OS thread with the |
| 131 |
event loop. See the :meth:`loop.run_in_executor` method for more |
| 132 |
details. |
| 133 |
|
| 134 |
|
| 135 |
.. _asyncio-logger: |
| 136 |
|
| 137 |
Logging |
| 138 |
======= |
| 139 |
|
| 140 |
asyncio uses the :mod:`logging` module and all logging is performed |
| 141 |
via the ``"asyncio"`` logger. |
| 142 |
|
| 143 |
The default log level is :py:const:`logging.INFO`, which can be easily |
| 144 |
adjusted:: |
| 145 |
|
| 146 |
logging.getLogger("asyncio").setLevel(logging.WARNING) |
| 147 |
|
| 148 |
|
| 149 |
Network logging can block the event loop. It is recommended to use |
| 150 |
a separate thread for handling logs or use non-blocking IO. For example, |
| 151 |
see :ref:`blocking-handlers`. |
| 152 |
|
| 153 |
|
| 154 |
.. _asyncio-coroutine-not-scheduled: |
| 155 |
|
| 156 |
Detect never-awaited coroutines |
| 157 |
=============================== |
| 158 |
|
| 159 |
When a coroutine function is called, but not awaited |
| 160 |
(e.g. ``coro()`` instead of ``await coro()``) |
| 161 |
or the coroutine is not scheduled with :meth:`asyncio.create_task`, asyncio |
| 162 |
will emit a :exc:`RuntimeWarning`:: |
| 163 |
|
| 164 |
import asyncio |
| 165 |
|
| 166 |
async def test(): |
| 167 |
print("never scheduled") |
| 168 |
|
| 169 |
async def main(): |
| 170 |
test() |
| 171 |
|
| 172 |
asyncio.run(main()) |
| 173 |
|
| 174 |
Output:: |
| 175 |
|
| 176 |
test.py:7: RuntimeWarning: coroutine 'test' was never awaited |
| 177 |
test() |
| 178 |
|
| 179 |
Output in debug mode:: |
| 180 |
|
| 181 |
test.py:7: RuntimeWarning: coroutine 'test' was never awaited |
| 182 |
Coroutine created at (most recent call last) |
| 183 |
File "../t.py", line 9, in <module> |
| 184 |
asyncio.run(main(), debug=True) |
| 185 |
|
| 186 |
< .. > |
| 187 |
|
| 188 |
File "../t.py", line 7, in main |
| 189 |
test() |
| 190 |
test() |
| 191 |
|
| 192 |
The usual fix is to either await the coroutine or call the |
| 193 |
:meth:`asyncio.create_task` function:: |
| 194 |
|
| 195 |
async def main(): |
| 196 |
await test() |
| 197 |
|
| 198 |
|
| 199 |
Detect never-retrieved exceptions |
| 200 |
================================= |
| 201 |
|
| 202 |
If a :meth:`Future.set_exception` is called but the Future object is |
| 203 |
never awaited on, the exception would never be propagated to the |
| 204 |
user code. In this case, asyncio would emit a log message when the |
| 205 |
Future object is garbage collected. |
| 206 |
|
| 207 |
Example of an unhandled exception:: |
| 208 |
|
| 209 |
import asyncio |
| 210 |
|
| 211 |
async def bug(): |
| 212 |
raise Exception("not consumed") |
| 213 |
|
| 214 |
async def main(): |
| 215 |
asyncio.create_task(bug()) |
| 216 |
|
| 217 |
asyncio.run(main()) |
| 218 |
|
| 219 |
Output:: |
| 220 |
|
| 221 |
Task exception was never retrieved |
| 222 |
future: <Task finished coro=<bug() done, defined at test.py:3> |
| 223 |
exception=Exception('not consumed')> |
| 224 |
|
| 225 |
Traceback (most recent call last): |
| 226 |
File "test.py", line 4, in bug |
| 227 |
raise Exception("not consumed") |
| 228 |
Exception: not consumed |
| 229 |
|
| 230 |
:ref:`Enable the debug mode <asyncio-debug-mode>` to get the |
| 231 |
traceback where the task was created:: |
| 232 |
|
| 233 |
asyncio.run(main(), debug=True) |
| 234 |
|
| 235 |
Output in debug mode:: |
| 236 |
|
| 237 |
Task exception was never retrieved |
| 238 |
future: <Task finished coro=<bug() done, defined at test.py:3> |
| 239 |
exception=Exception('not consumed') created at asyncio/tasks.py:321> |
| 240 |
|
| 241 |
source_traceback: Object created at (most recent call last): |
| 242 |
File "../t.py", line 9, in <module> |
| 243 |
asyncio.run(main(), debug=True) |
| 244 |
|
| 245 |
< .. > |
| 246 |
|
| 247 |
Traceback (most recent call last): |
| 248 |
File "../t.py", line 4, in bug |
| 249 |
raise Exception("not consumed") |
| 250 |
Exception: not consumed |
| 251 |
|
| 252 |
|
| 253 |
Asynchronous generators best practices |
| 254 |
====================================== |
| 255 |
|
| 256 |
Writing correct and efficient asyncio code requires awareness of certain pitfalls. |
| 257 |
This section outlines essential best practices that can save you hours of debugging. |
| 258 |
|
| 259 |
|
| 260 |
Close asynchronous generators explicitly |
| 261 |
---------------------------------------- |
| 262 |
|
| 263 |
It is recommended to manually close the |
| 264 |
:term:`asynchronous generator <asynchronous generator iterator>`. If a generator |
| 265 |
exits early - for example, due to an exception raised in the body of |
| 266 |
an ``async for`` loop - its asynchronous cleanup code may run in an |
| 267 |
unexpected context. This can occur after the tasks it depends on have completed, |
| 268 |
or during the event loop shutdown when the async-generator's garbage collection |
| 269 |
hook is called. |
| 270 |
|
| 271 |
To avoid this, explicitly close the generator by calling its |
| 272 |
:meth:`~agen.aclose` method, or use the :func:`contextlib.aclosing` |
| 273 |
context manager:: |
| 274 |
|
| 275 |
import asyncio |
| 276 |
import contextlib |
| 277 |
|
| 278 |
async def gen(): |
| 279 |
yield 1 |
| 280 |
yield 2 |
| 281 |
|
| 282 |
async def func(): |
| 283 |
async with contextlib.aclosing(gen()) as g: |
| 284 |
async for x in g: |
| 285 |
break # Don't iterate until the end |
| 286 |
|
| 287 |
asyncio.run(func()) |
| 288 |
|
| 289 |
As noted above, the cleanup code for these asynchronous generators is deferred. |
| 290 |
The following example demonstrates that the finalization of an asynchronous |
| 291 |
generator can occur in an unexpected order:: |
| 292 |
|
| 293 |
import asyncio |
| 294 |
work_done = False |
| 295 |
|
| 296 |
async def cursor(): |
| 297 |
try: |
| 298 |
yield 1 |
| 299 |
finally: |
| 300 |
assert work_done |
| 301 |
|
| 302 |
async def rows(): |
| 303 |
global work_done |
| 304 |
try: |
| 305 |
yield 2 |
| 306 |
finally: |
| 307 |
await asyncio.sleep(0.1) # immitate some async work |
| 308 |
work_done = True |
| 309 |
|
| 310 |
|
| 311 |
async def main(): |
| 312 |
async for c in cursor(): |
| 313 |
async for r in rows(): |
| 314 |
break |
| 315 |
break |
| 316 |
|
| 317 |
asyncio.run(main()) |
| 318 |
|
| 319 |
For this example, we get the following output:: |
| 320 |
|
| 321 |
unhandled exception during asyncio.run() shutdown |
| 322 |
task: <Task finished name='Task-3' coro=<<async_generator_athrow without __name__>()> exception=AssertionError()> |
| 323 |
Traceback (most recent call last): |
| 324 |
File "example.py", line 6, in cursor |
| 325 |
yield 1 |
| 326 |
asyncio.exceptions.CancelledError |
| 327 |
|
| 328 |
During handling of the above exception, another exception occurred: |
| 329 |
|
| 330 |
Traceback (most recent call last): |
| 331 |
File "example.py", line 8, in cursor |
| 332 |
assert work_done |
| 333 |
^^^^^^^^^ |
| 334 |
AssertionError |
| 335 |
|
| 336 |
The ``cursor()`` asynchronous generator was finalized before the ``rows`` |
| 337 |
generator - an unexpected behavior. |
| 338 |
|
| 339 |
The example can be fixed by explicitly closing the |
| 340 |
``cursor`` and ``rows`` async-generators:: |
| 341 |
|
| 342 |
async def main(): |
| 343 |
async with contextlib.aclosing(cursor()) as cursor_gen: |
| 344 |
async for c in cursor_gen: |
| 345 |
async with contextlib.aclosing(rows()) as rows_gen: |
| 346 |
async for r in rows_gen: |
| 347 |
break |
| 348 |
break |
| 349 |
|
| 350 |
|
| 351 |
Create asynchronous generators only when the event loop is running |
| 352 |
------------------------------------------------------------------ |
| 353 |
|
| 354 |
It is recommended to create |
| 355 |
:term:`asynchronous generators <asynchronous generator iterator>` only after |
| 356 |
the event loop has been created. |
| 357 |
|
| 358 |
To ensure that asynchronous generators close reliably, the event loop uses the |
| 359 |
:func:`sys.set_asyncgen_hooks` function to register callback functions. These |
| 360 |
callbacks update the list of running asynchronous generators to keep it in a |
| 361 |
consistent state. |
| 362 |
|
| 363 |
When the :meth:`loop.shutdown_asyncgens() <asyncio.loop.shutdown_asyncgens>` |
| 364 |
function is called, the running generators are stopped gracefully and the |
| 365 |
list is cleared. |
| 366 |
|
| 367 |
The asynchronous generator invokes the corresponding system hook during its |
| 368 |
first iteration. At the same time, the generator records that the hook has |
| 369 |
been called and does not call it again. |
| 370 |
|
| 371 |
Therefore, if iteration begins before the event loop is created, |
| 372 |
the event loop will not be able to add the generator to its list of active |
| 373 |
generators because the hooks are set after the generator attempts to call them. |
| 374 |
Consequently, the event loop will not be able to terminate the generator |
| 375 |
if necessary. |
| 376 |
|
| 377 |
Consider the following example:: |
| 378 |
|
| 379 |
import asyncio |
| 380 |
|
| 381 |
async def agenfn(): |
| 382 |
try: |
| 383 |
yield 10 |
| 384 |
finally: |
| 385 |
await asyncio.sleep(0) |
| 386 |
|
| 387 |
|
| 388 |
with asyncio.Runner() as runner: |
| 389 |
agen = agenfn() |
| 390 |
print(runner.run(anext(agen))) |
| 391 |
del agen |
| 392 |
|
| 393 |
Output:: |
| 394 |
|
| 395 |
10 |
| 396 |
Exception ignored while closing generator <async_generator object agenfn at 0x000002F71CD10D70>: |
| 397 |
Traceback (most recent call last): |
| 398 |
File "example.py", line 13, in <module> |
| 399 |
del agen |
| 400 |
^^^^ |
| 401 |
RuntimeError: async generator ignored GeneratorExit |
| 402 |
|
| 403 |
This example can be fixed as follows:: |
| 404 |
|
| 405 |
import asyncio |
| 406 |
|
| 407 |
async def agenfn(): |
| 408 |
try: |
| 409 |
yield 10 |
| 410 |
finally: |
| 411 |
await asyncio.sleep(0) |
| 412 |
|
| 413 |
async def main(): |
| 414 |
agen = agenfn() |
| 415 |
print(await anext(agen)) |
| 416 |
del agen |
| 417 |
|
| 418 |
asyncio.run(main()) |
| 419 |
|
| 420 |
|
| 421 |
Avoid concurrent iteration and closure of the same generator |
| 422 |
------------------------------------------------------------ |
| 423 |
|
| 424 |
Async generators may be reentered while another |
| 425 |
:meth:`~agen.__anext__` / :meth:`~agen.athrow` / :meth:`~agen.aclose` call is in |
| 426 |
progress. This may lead to an inconsistent state of the async generator and can |
| 427 |
cause errors. |
| 428 |
|
| 429 |
Let's consider the following example:: |
| 430 |
|
| 431 |
import asyncio |
| 432 |
|
| 433 |
async def consumer(): |
| 434 |
for idx in range(100): |
| 435 |
await asyncio.sleep(0) |
| 436 |
message = yield idx |
| 437 |
print('received', message) |
| 438 |
|
| 439 |
async def amain(): |
| 440 |
agenerator = consumer() |
| 441 |
await agenerator.asend(None) |
| 442 |
|
| 443 |
fa = asyncio.create_task(agenerator.asend('A')) |
| 444 |
fb = asyncio.create_task(agenerator.asend('B')) |
| 445 |
await fa |
| 446 |
await fb |
| 447 |
|
| 448 |
asyncio.run(amain()) |
| 449 |
|
| 450 |
Output:: |
| 451 |
|
| 452 |
received A |
| 453 |
Traceback (most recent call last): |
| 454 |
File "test.py", line 38, in <module> |
| 455 |
asyncio.run(amain()) |
| 456 |
~~~~~~~~~~~^^^^^^^^^ |
| 457 |
File "Lib/asyncio/runners.py", line 204, in run |
| 458 |
return runner.run(main) |
| 459 |
~~~~~~~~~~^^^^^^ |
| 460 |
File "Lib/asyncio/runners.py", line 127, in run |
| 461 |
return self._loop.run_until_complete(task) |
| 462 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^ |
| 463 |
File "Lib/asyncio/base_events.py", line 719, in run_until_complete |
| 464 |
return future.result() |
| 465 |
~~~~~~~~~~~~~^^ |
| 466 |
File "test.py", line 36, in amain |
| 467 |
await fb |
| 468 |
RuntimeError: anext(): asynchronous generator is already running |
| 469 |
|
| 470 |
|
| 471 |
Therefore, it is recommended to avoid using asynchronous generators in parallel |
| 472 |
tasks or across multiple event loops. |