gh-94972: document that shield users need to keep a reference to their task (#96724)

Co-authored-by: Thomas Grainger <tagrain@gmail.com>
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>

1 files changed, 9 insertions, 2 deletions

diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
index 27fe58d..56a355c 100644
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -848,7 +848,8 @@ def shield(arg):
 
     The statement
 
-        res = await shield(something())
+        task = asyncio.create_task(something())
+        res = await shield(task)
 
     is exactly equivalent to the statement
 
@@ -864,10 +865,16 @@ def shield(arg):
     If you want to completely ignore cancellation (not recommended)
     you can combine shield() with a try/except clause, as follows:
 
+        task = asyncio.create_task(something())
         try:
-            res = await shield(something())
+            res = await shield(task)
         except CancelledError:
             res = None
+
+    Save a reference to tasks passed to this function, to avoid
+    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.
     """
     inner = _ensure_future(arg)
     if inner.done():