Skip to content

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

Closed
wants to merge 6 commits into from

Conversation

graingert
Copy link
Contributor

@graingert graingert commented Jul 18, 2022

@graingert graingert requested review from 1st1 and asvetlov as code owners July 18, 2022 16:45
@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news awaiting review labels Jul 18, 2022
Comment on lines 555 to 560
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Contributor Author

@graingert graingert Jul 19, 2022

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"

Copy link
Contributor Author

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, sure.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Akasurde done!

Copy link
Member

@gvanrossum gvanrossum left a 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]>
Copy link
Member

@gvanrossum gvanrossum left a 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...

@kumaraditya303 kumaraditya303 added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Aug 25, 2022
@gvanrossum
Copy link
Member

gvanrossum commented Aug 29, 2022

The "eyes" emoji must be one of the most ambiguous emoji ever.

I wrote

Please also update the docstring for shield() itself, since it repeats the same advice.

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.

@hendrikmakait
Copy link
Contributor

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.

@gvanrossum
Copy link
Member

Okay, closing.

@gvanrossum gvanrossum closed this Sep 9, 2022
@graingert
Copy link
Contributor Author

Closing this in favor of #96724

@graingert graingert deleted the shield branch September 10, 2022 05:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants