From c7b5a2d5eafd40d2dd242383b4db7c15d26e8fbc Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 7 Jun 2022 03:14:25 -0700
Subject: [PATCH] gh-88831: In docs for asyncio.create_task, explain why strong
 references to tasks are needed (GH-93258) (GH-93567)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

Co-authored-by: Andreas Grommek <76997441+agrommek@users.noreply.github.com>
---
 Doc/library/asyncio-task.rst                  | 19 ++++++++++++++++++-
 ...2-05-26-14-51-25.gh-issue-88831.5Cccr5.rst |  1 +
 2 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2022-05-26-14-51-25.gh-issue-88831.5Cccr5.rst

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index dc09286e5f852d..e535a5bf042542 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -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
 
diff --git a/Misc/NEWS.d/next/Documentation/2022-05-26-14-51-25.gh-issue-88831.5Cccr5.rst b/Misc/NEWS.d/next/Documentation/2022-05-26-14-51-25.gh-issue-88831.5Cccr5.rst
new file mode 100644
index 00000000000000..983bea981a9b20
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-05-26-14-51-25.gh-issue-88831.5Cccr5.rst
@@ -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.