Debian Codegraph @

Doc/library/asyncio-dev.rst

raw
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.