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` to execute
103 blocking code in a different OS thread without blocking the OS thread
104 that the event loop runs in.
105
106 There is currently no way to schedule coroutines or callbacks directly
107 from a different process (such as one started with
108 :mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods`
109 section lists APIs that can read from pipes and watch file descriptors
110 without blocking the event loop. In addition, asyncio's
111 :ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a
112 process and communicate with it from the event loop. Lastly, the
113 aforementioned :meth:`loop.run_in_executor` method can also be used
114 with a :class:`concurrent.futures.ProcessPoolExecutor` to execute
115 code in a different process.
116
117 .. _asyncio-handle-blocking:
118
119 Running Blocking Code
120 =====================
121
122 Blocking (CPU-bound) code should not be called directly. For example,
123 if a function performs a CPU-intensive calculation for 1 second,
124 all concurrent asyncio Tasks and IO operations would be delayed
125 by 1 second.
126
127 An executor can be used to run a task in a different thread or even in
128 a different process to avoid blocking the OS thread with the
129 event loop. See the :meth:`loop.run_in_executor` method for more
130 details.
131
132
133 .. _asyncio-logger:
134
135 Logging
136 =======
137
138 asyncio uses the :mod:`logging` module and all logging is performed
139 via the ``"asyncio"`` logger.
140
141 The default log level is :py:const:`logging.INFO`, which can be easily
142 adjusted::
143
144 logging.getLogger("asyncio").setLevel(logging.WARNING)
145
146
147 Network logging can block the event loop. It is recommended to use
148 a separate thread for handling logs or use non-blocking IO. For example,
149 see :ref:`blocking-handlers`.
150
151
152 .. _asyncio-coroutine-not-scheduled:
153
154 Detect never-awaited coroutines
155 ===============================
156
157 When a coroutine function is called, but not awaited
158 (e.g. ``coro()`` instead of ``await coro()``)
159 or the coroutine is not scheduled with :meth:`asyncio.create_task`, asyncio
160 will emit a :exc:`RuntimeWarning`::
161
162 import asyncio
163
164 async def test():
165 print("never scheduled")
166
167 async def main():
168 test()
169
170 asyncio.run(main())
171
172 Output::
173
174 test.py:7: RuntimeWarning: coroutine 'test' was never awaited
175 test()
176
177 Output in debug mode::
178
179 test.py:7: RuntimeWarning: coroutine 'test' was never awaited
180 Coroutine created at (most recent call last)
181 File "../t.py", line 9, in <module>
182 asyncio.run(main(), debug=True)
183
184 < .. >
185
186 File "../t.py", line 7, in main
187 test()
188 test()
189
190 The usual fix is to either await the coroutine or call the
191 :meth:`asyncio.create_task` function::
192
193 async def main():
194 await test()
195
196
197 Detect never-retrieved exceptions
198 =================================
199
200 If a :meth:`Future.set_exception` is called but the Future object is
201 never awaited on, the exception would never be propagated to the
202 user code. In this case, asyncio would emit a log message when the
203 Future object is garbage collected.
204
205 Example of an unhandled exception::
206
207 import asyncio
208
209 async def bug():
210 raise Exception("not consumed")
211
212 async def main():
213 asyncio.create_task(bug())
214
215 asyncio.run(main())
216
217 Output::
218
219 Task exception was never retrieved
220 future: <Task finished coro=<bug() done, defined at test.py:3>
221 exception=Exception('not consumed')>
222
223 Traceback (most recent call last):
224 File "test.py", line 4, in bug
225 raise Exception("not consumed")
226 Exception: not consumed
227
228 :ref:`Enable the debug mode <asyncio-debug-mode>` to get the
229 traceback where the task was created::
230
231 asyncio.run(main(), debug=True)
232
233 Output in debug mode::
234
235 Task exception was never retrieved
236 future: <Task finished coro=<bug() done, defined at test.py:3>
237 exception=Exception('not consumed') created at asyncio/tasks.py:321>
238
239 source_traceback: Object created at (most recent call last):
240 File "../t.py", line 9, in <module>
241 asyncio.run(main(), debug=True)
242
243 < .. >
244
245 Traceback (most recent call last):
246 File "../t.py", line 4, in bug
247 raise Exception("not consumed")
248 Exception: not consumed
249
250
251 Asynchronous generators best practices
252 ======================================
253
254 Writing correct and efficient asyncio code requires awareness of certain pitfalls.
255 This section outlines essential best practices that can save you hours of debugging.
256
257
258 Close asynchronous generators explicitly
259 ----------------------------------------
260
261 It is recommended to manually close the
262 :term:`asynchronous generator <asynchronous generator iterator>`. If a generator
263 exits early - for example, due to an exception raised in the body of
264 an ``async for`` loop - its asynchronous cleanup code may run in an
265 unexpected context. This can occur after the tasks it depends on have completed,
266 or during the event loop shutdown when the async-generator's garbage collection
267 hook is called.
268
269 To avoid this, explicitly close the generator by calling its
270 :meth:`~agen.aclose` method, or use the :func:`contextlib.aclosing`
271 context manager::
272
273 import asyncio
274 import contextlib
275
276 async def gen():
277 yield 1
278 yield 2
279
280 async def func():
281 async with contextlib.aclosing(gen()) as g:
282 async for x in g:
283 break # Don't iterate until the end
284
285 asyncio.run(func())
286
287 As noted above, the cleanup code for these asynchronous generators is deferred.
288 The following example demonstrates that the finalization of an asynchronous
289 generator can occur in an unexpected order::
290
291 import asyncio
292 work_done = False
293
294 async def cursor():
295 try:
296 yield 1
297 finally:
298 assert work_done
299
300 async def rows():
301 global work_done
302 try:
303 yield 2
304 finally:
305 await asyncio.sleep(0.1) # immitate some async work
306 work_done = True
307
308
309 async def main():
310 async for c in cursor():
311 async for r in rows():
312 break
313 break
314
315 asyncio.run(main())
316
317 For this example, we get the following output::
318
319 unhandled exception during asyncio.run() shutdown
320 task: <Task finished name='Task-3' coro=<<async_generator_athrow without __name__>()> exception=AssertionError()>
321 Traceback (most recent call last):
322 File "example.py", line 6, in cursor
323 yield 1
324 asyncio.exceptions.CancelledError
325
326 During handling of the above exception, another exception occurred:
327
328 Traceback (most recent call last):
329 File "example.py", line 8, in cursor
330 assert work_done
331 ^^^^^^^^^
332 AssertionError
333
334 The ``cursor()`` asynchronous generator was finalized before the ``rows``
335 generator - an unexpected behavior.
336
337 The example can be fixed by explicitly closing the
338 ``cursor`` and ``rows`` async-generators::
339
340 async def main():
341 async with contextlib.aclosing(cursor()) as cursor_gen:
342 async for c in cursor_gen:
343 async with contextlib.aclosing(rows()) as rows_gen:
344 async for r in rows_gen:
345 break
346 break
347
348
349 Create asynchronous generators only when the event loop is running
350 ------------------------------------------------------------------
351
352 It is recommended to create
353 :term:`asynchronous generators <asynchronous generator iterator>` only after
354 the event loop has been created.
355
356 To ensure that asynchronous generators close reliably, the event loop uses the
357 :func:`sys.set_asyncgen_hooks` function to register callback functions. These
358 callbacks update the list of running asynchronous generators to keep it in a
359 consistent state.
360
361 When the :meth:`loop.shutdown_asyncgens() <asyncio.loop.shutdown_asyncgens>`
362 function is called, the running generators are stopped gracefully and the
363 list is cleared.
364
365 The asynchronous generator invokes the corresponding system hook during its
366 first iteration. At the same time, the generator records that the hook has
367 been called and does not call it again.
368
369 Therefore, if iteration begins before the event loop is created,
370 the event loop will not be able to add the generator to its list of active
371 generators because the hooks are set after the generator attempts to call them.
372 Consequently, the event loop will not be able to terminate the generator
373 if necessary.
374
375 Consider the following example::
376
377 import asyncio
378
379 async def agenfn():
380 try:
381 yield 10
382 finally:
383 await asyncio.sleep(0)
384
385
386 with asyncio.Runner() as runner:
387 agen = agenfn()
388 print(runner.run(anext(agen)))
389 del agen
390
391 Output::
392
393 10
394 Exception ignored while closing generator <async_generator object agenfn at 0x000002F71CD10D70>:
395 Traceback (most recent call last):
396 File "example.py", line 13, in <module>
397 del agen
398 ^^^^
399 RuntimeError: async generator ignored GeneratorExit
400
401 This example can be fixed as follows::
402
403 import asyncio
404
405 async def agenfn():
406 try:
407 yield 10
408 finally:
409 await asyncio.sleep(0)
410
411 async def main():
412 agen = agenfn()
413 print(await anext(agen))
414 del agen
415
416 asyncio.run(main())
417
418
419 Avoid concurrent iteration and closure of the same generator
420 ------------------------------------------------------------
421
422 Async generators may be reentered while another
423 :meth:`~agen.__anext__` / :meth:`~agen.athrow` / :meth:`~agen.aclose` call is in
424 progress. This may lead to an inconsistent state of the async generator and can
425 cause errors.
426
427 Let's consider the following example::
428
429 import asyncio
430
431 async def consumer():
432 for idx in range(100):
433 await asyncio.sleep(0)
434 message = yield idx
435 print('received', message)
436
437 async def amain():
438 agenerator = consumer()
439 await agenerator.asend(None)
440
441 fa = asyncio.create_task(agenerator.asend('A'))
442 fb = asyncio.create_task(agenerator.asend('B'))
443 await fa
444 await fb
445
446 asyncio.run(amain())
447
448 Output::
449
450 received A
451 Traceback (most recent call last):
452 File "test.py", line 38, in <module>
453 asyncio.run(amain())
454 ~~~~~~~~~~~^^^^^^^^^
455 File "Lib/asyncio/runners.py", line 204, in run
456 return runner.run(main)
457 ~~~~~~~~~~^^^^^^
458 File "Lib/asyncio/runners.py", line 127, in run
459 return self._loop.run_until_complete(task)
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
461 File "Lib/asyncio/base_events.py", line 719, in run_until_complete
462 return future.result()
463 ~~~~~~~~~~~~~^^
464 File "test.py", line 36, in amain
465 await fb
466 RuntimeError: anext(): asynchronous generator is already running
467
468
469 Therefore, it is recommended to avoid using asynchronous generators in parallel
470 tasks or across multiple event loops.