-
-
Notifications
You must be signed in to change notification settings - Fork 32k
gh-94972: document that shield users need to keep a reference to their task #94973
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
graingert
commented
Jul 18, 2022
•
edited by bedevere-bot
Loading
edited by bedevere-bot
- Issue: shield() documentation should mention user needs to keep reference to the task #94972
Doc/library/asyncio-task.rst
Outdated
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. | ||
For reliable "fire-and-forget" background tasks, gather them in | ||
a collection. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. | |
For reliable "fire-and-forget" background tasks, gather them in | |
a collection. | |
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. | |
For reliable "fire-and-forget" background tasks, gather them in | |
a collection. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This PR adapts the documentation from asyncio.create_task
and so inherits the hyphenation style.
there's already one use of "mid execution" in cpython and 1 use of "mid-execution" (that's asyncio.create_task where I copied this from)
there's 54 uses of "garbage collected" and only 25 uses of "garbage-collected"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Akasurde do you want me to change all of these?
graingert@superjacent testing310 ~/projects/cpython shield git grep "mid-execution"
✘ graingert@superjacent testing310 ~/projects/cpython shield git grep "mid execution"
Doc/library/asyncio-future.rst: a task disappearing mid execution.
Doc/library/asyncio-task.rst: a task disappearing mid execution. The event loop only keeps
Doc/library/asyncio-task.rst: a task disappearing mid execution. The event loop only keeps
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, sure.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Akasurde done!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please also update the docstring for shield()
itself, since it repeats the same advice.
Co-authored-by: Guido van Rossum <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Waiting for the shield() docstring update...
The "eyes" emoji must be one of the most ambiguous emoji ever. I wrote
I recommend adding something like "Save a reference to tasks passed to this function, to avoid a task being garbage-collected mid-execution." to the docstring for shield() in asyncio/tasks.py. |
As discussed offline with @graingert, I will take over the remaining work on this PR to make sure we get this over the finish line. See #96724 for new PR. |
Okay, closing. |
Closing this in favor of #96724 |