Skip to content

Commit

Permalink
gh-88831: In docs for asyncio.create_task, explain why strong referen…
Browse files Browse the repository at this point in the history
…ces to tasks are needed (GH-93258) (GH-93567)

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit 75ceae0)

Co-authored-by: Andreas Grommek <76997441+agrommek@users.noreply.github.com>
  • Loading branch information
miss-islington and agrommek authored Jun 7, 2022
1 parent 9204364 commit c7b5a2d
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 1 deletion.
19 changes: 18 additions & 1 deletion Doc/library/asyncio-task.rst
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,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

Expand Down
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit c7b5a2d

Please sign in to comment.