shield() documentation should mention user needs to keep reference to the task

Documentation

asyncio will only keep weak references to alive tasks (in _all_tasks). If a user does not keep a reference to a task and the task is not currently executing or sleeping, the user may get "Task was destroyed but it is pending!".

See also #93297

@kumaraditya303

@kumaraditya303 here's the repro on python3.10:

import weakref
import asyncio
import gc

import logging


logger = logging.getLogger(__name__)


async def async_fn():
    try:
        await asyncio.get_running_loop().create_future()
    except BaseException:
        logger.exception("closed!")
        raise


async def amain():
    weak_task = weakref.ref(asyncio.create_task(async_fn()))
    await asyncio.sleep(0.01)
    gc.collect()
    print(weak_task())


async def sheild_gc():
    strong_shielded_fut = asyncio.shield(async_fn())
    await asyncio.sleep(0)
    asyncio.current_task().cancel()
    try:
        await strong_shielded_fut
    except asyncio.CancelledError:
        pass

    gc.collect()


asyncio.run(amain())
print("======================")
asyncio.run(sheild_gc())

output:

closed!
Traceback (most recent call last):
  File "/home/graingert/projects/foo.py", line 14, in async_fn
    await asyncio.get_running_loop().create_future()
GeneratorExit
Task was destroyed but it is pending!
task: <Task pending name='Task-2' coro=<async_fn() done, defined at /home/graingert/projects/foo.py:12> wait_for=<Future pending cb=[Task.task_wakeup()]>>
None
======================
closed!
Traceback (most recent call last):
  File "/home/graingert/projects/foo.py", line 14, in async_fn
    await asyncio.get_running_loop().create_future()
GeneratorExit
Task was destroyed but it is pending!
task: <Task pending name='Task-6' coro=<async_fn() done, defined at /home/graingert/projects/foo.py:12> wait_for=<Future pending cb=[Task.task_wakeup()]>>

Are you too busy to submit a PR that updates the docs?

There's one linked here #94973

I think I get the same output on 3.11. Question, is import objgraph needed in the repro? (I had to delete it, no idea what it is.)

gh-94972: document that shield users need to keep a reference to thei…

pythongh-94972: document that shield users need to keep a reference t…

gh-94972: document that shield users need to keep a reference to thei…

I think I get the same output on 3.11. Question, is import objgraph needed in the repro? (I had to delete it, no idea what it is.)

Left in by accident. It's not needed to cause the error but I used it to help build it

Keep reference to background tasks.

Navigation Menu

Repository navigation

shield() documentation should mention user needs to keep reference to the task #94972

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

shield() documentation should mention user needs to keep reference to the task #94972

Description

Activity

kumaraditya303 commented on Jul 22, 2022

graingert commented on Jul 22, 2022

graingert commented on Jul 22, 2022

gvanrossum commented on Aug 24, 2022

graingert commented on Aug 24, 2022

gvanrossum commented on Aug 29, 2022

graingert commented on Sep 12, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions