gh-88831: In docs for asyncio.create_task, explain why strong references to tasks are needed (GH-93258)

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
This commit is contained in:
Andreas Grommek 2022-06-07 10:56:09 +02:00 committed by GitHub
parent f0d0be3493
commit 75ceae05c1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 19 additions and 1 deletions

View file

@ -226,7 +226,24 @@ Creating Tasks
.. important::
Save a reference to the result of this function, to avoid
a task disappearing mid execution.
a task disappearing mid execution. The event loop only keeps
weak references to tasks. A task that isn't referenced elsewhere
may get garbage-collected at any time, even before it's done.
For reliable "fire-and-forget" background tasks, gather them in
a collection::
background_tasks = set()
for i in range(10):
task = asyncio.create_task(some_coro(param=i))
# Add task to the set. This creates a strong reference.
background_tasks.add(task)
# To prevent keeping references to finished tasks forever,
# make each task remove its own reference from the set after
# completion:
task.add_done_callback(background_tasks.discard)
.. versionadded:: 3.7

View file

@ -0,0 +1 @@
Augmented documentation of asyncio.create_task(). Clarified the need to keep strong references to tasks and added a code snippet detailing how to to this.