Skip to content
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

context: CancelFunc isn't documented to be safe for simultaneous use by multiple goroutines #32145

Closed
dmitshur opened this issue May 19, 2019 · 2 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@dmitshur
Copy link
Contributor

dmitshur commented May 19, 2019

There are two types defined in the context package. The documentation makes it very clear that the context.Context type and its methods are safe for simultaneous use by multiple goroutines:

  • In the package comment:

    The same Context may be passed to functions running in different goroutines; Contexts are safe for simultaneous use by multiple goroutines.

  • In the context.Context type documentation:

    Context's methods may be called by multiple goroutines simultaneously.

There is another type in the context package, the context.CancelFunc type. It is currently documented as:

A CancelFunc tells an operation to abandon its work. A CancelFunc does not wait for the work to stop. After the first call, subsequent calls to a CancelFunc do nothing.

It states that after the first call, subsequent calls to a CancelFunc do nothing. The three With* methods that return a Context and CancelFunc say:

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

As I understand it, the documentation does not state that ContextFunc is safe for simultaneous use by multiple goroutines. Is that a documentation bug?

/cc @Sajmani, @bradfitz as owners; also /cc @mvdan

@dmitshur dmitshur added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels May 19, 2019
@dmitshur dmitshur added this to the Go1.13 milestone May 19, 2019
@neild
Copy link
Contributor

neild commented May 19, 2019

A CancelFunc is intended to be safe for concurrent use, so that's a documentation bug if "subsequent calls do nothing" isn't clear enough.

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels May 19, 2019
@gopherbot
Copy link

Change https://golang.org/cl/177899 mentions this issue: context: document CancelFunc to be safe for simultaneous use by multiple goroutines

dmitshur added a commit to shurcooL/home that referenced this issue Jun 16, 2019
If the HTTP server fails (e.g., fails to start listening on
the specified port because it's already taken), we want to
cancel all other components and exit right away. Do so by
canceling the application-level context when that happens.

Updates golang/go#32145
@golang golang locked and limited conversation to collaborators May 19, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

3 participants