diff options
| -rw-r--r-- | Doc/library/asyncio-future.rst | 2 | ||||
| -rw-r--r-- | Doc/library/asyncio-task.rst | 17 | ||||
| -rw-r--r-- | Lib/asyncio/tasks.py | 11 |
3 files changed, 23 insertions, 7 deletions
diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst index f74f2e6..99a5d3a 100644 --- a/Doc/library/asyncio-future.rst +++ b/Doc/library/asyncio-future.rst @@ -55,7 +55,7 @@ Future Functions preferred way for creating new Tasks. Save a reference to the result of this function, to avoid - a task disappearing mid execution. + a task disappearing mid-execution. .. versionchanged:: 3.5.1 The function accepts any :term:`awaitable` object. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index ffbf421..221197e 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -254,9 +254,9 @@ Creating Tasks .. important:: Save a reference to the result of this function, to avoid - a task disappearing mid execution. The event loop only keeps + 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. + may get garbage collected at any time, even before it's done. For reliable "fire-and-forget" background tasks, gather them in a collection:: @@ -520,7 +520,8 @@ Shielding From Cancellation The statement:: - res = await shield(something()) + task = asyncio.create_task(something()) + res = await shield(task) is equivalent to:: @@ -539,11 +540,19 @@ Shielding From Cancellation the ``shield()`` function should be combined 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 + .. important:: + + 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. + .. versionchanged:: 3.10 Removed the *loop* parameter. 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(): |