asyncio.create_task() documentation should mention user needs to keep reference to the task

[vincentbernat]

BPO	44665
Nosy	@cmeyer, @nanjekyejoannah, @vincentbernat, @alexhartl
PRs	bpo-44665: asyncio.create_task() documentation should mention user needs to keep reference to the task #29163

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-07-18.06:01:26.261>
labels = ['3.11', 'type-feature', '3.9', '3.10', 'docs']
title = 'asyncio.create_task() documentation should mention user needs to keep reference to the task'
updated_at = <Date 2022-01-06.08:53:46.602>
user = 'https://github.com/vincentbernat'

bugs.python.org fields:

activity = <Date 2022-01-06.08:53:46.602>
actor = 'alexhartl'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-07-18.06:01:26.261>
creator = 'bernat'
dependencies = []
files = []
hgrepos = []
issue_num = 44665
keywords = ['patch']
message_count = 5.0
messages = ['397741', '404776', '404782', '404827', '409821']
nosy_count = 5.0
nosy_names = ['docs@python', 'cmeyer', 'nanjekyejoannah', 'bernat', 'alexhartl']
pr_nums = ['29163']
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44665'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[vincentbernat]

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!".

I would suggest adding the following paragraph to create_task() documentation:

Python only keeps weak references to the scheduled tasks. To avoid the task being destroyed by the garbage collector while still pending, a reference to it should be kept until the task is done.

And maybe an example in case a user wants something "fire and forget"?

running_tasks = set()
# [...]
task = asyncio.create_task(some_background_function())
running_tasks.add(task)
task.add_done_callback(lambda t: running_tasks.remove(t))

The same applies to ensure_future as it now uses create_task, so maybe a "See create_task()".

[nanjekyejoannah]

@bernat and ncoghlan, please see if the wording I have used in the linked PR helps to clarify this.

[cmeyer]

Is there a way to reproduce this issue? I run the following code in Python 3.9 and it works as expected (prints "xyz" twice).

import asyncio
import gc

async def xyz():
 print("xyz")

event_loop = asyncio.get_event_loop()

event_loop.create_task(xyz())

t = event_loop.create_task(xyz())
del t

gc.collect()

event_loop.stop()
event_loop.run_forever()