clones/go
1
0
Fork 0
mirror of https://github.com/golang/go.git synced 2024-09-21 10:28:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

context: document that WithValue returns a derived context

Browse Source 
Also replace "copy of parent" with "derived context" in doc comments.

Fixes #68923

Change-Id: I319c1594f390e35b32b4e58ee979927bb84bfdf9
Reviewed-on: https://go-review.googlesource.com/c/go/+/606555
Reviewed-by: Sameer Ajmani <sameer@golang.org>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Sameer Ajmani <sameer@golang.org>
Commit-Queue: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
This commit is contained in:
Ian Lance Taylor 2024-08-17 17:53:19 -07:00 committed by Gopher Robot
parent fc9f02c7ae
commit a9e6a96ac0
1 changed files with 14 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/context/context.go
View File

@ -226,9 +226,10 @@ func TODO() Context {
// After the first call, subsequent calls to a CancelFunc do nothing. // After the first call, subsequent calls to a CancelFunc do nothing.
type CancelFunc func() type CancelFunc func()
// WithCancel returns a copy of parent with a new Done channel. The returned // WithCancel returns a derived context that points to the parent context
// context's Done channel is closed when the returned cancel function is called // but has a new Done channel. The returned context's Done channel is closed
// or when the parent context's Done channel is closed, whichever happens first. // when the returned cancel function is called or when the parent context's
// Done channel is closed, whichever happens first.
// //
// Canceling this context releases resources associated with it, so code should // Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this [Context] complete. // call cancel as soon as the operations running in this [Context] complete.
@ -565,7 +566,8 @@ func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
} }
} }
// WithoutCancel returns a copy of parent that is not canceled when parent is canceled. // WithoutCancel returns a derived context that points to the parent context
// and is not canceled when parent is canceled.
// The returned context returns no Deadline or Err, and its Done channel is nil. // The returned context returns no Deadline or Err, and its Done channel is nil.
// Calling [Cause] on the returned context returns nil. // Calling [Cause] on the returned context returns nil.
func WithoutCancel(parent Context) Context { func WithoutCancel(parent Context) Context {
@ -599,12 +601,12 @@ func (c withoutCancelCtx) String() string {
return contextName(c.c) + ".WithoutCancel" return contextName(c.c) + ".WithoutCancel"
} }
// WithDeadline returns a copy of the parent context with the deadline adjusted // WithDeadline returns a derived context that points to the parent context
// to be no later than d. If the parent's deadline is already earlier than d, // but has the deadline adjusted to be no later than d. If the parent's
// WithDeadline(parent, d) is semantically equivalent to parent. The returned // deadline is already earlier than d, WithDeadline(parent, d) is semantically
// [Context.Done] channel is closed when the deadline expires, when the returned // equivalent to parent. The returned [Context.Done] channel is closed when
// cancel function is called, or when the parent context's Done channel is // the deadline expires, when the returned cancel function is called,
// closed, whichever happens first. // or when the parent context's Done channel is closed, whichever happens first.
// //
// Canceling this context releases resources associated with it, so code should // Canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this [Context] complete. // call cancel as soon as the operations running in this [Context] complete.
@ -697,8 +699,8 @@ func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Conte
return WithDeadlineCause(parent, time.Now().Add(timeout), cause) return WithDeadlineCause(parent, time.Now().Add(timeout), cause)
} }
// WithValue returns a copy of parent in which the value associated with key is // WithValue returns a derived context that points to the parent Context.
// val. // In the derived context, the value associated with key is val.
// //
// Use context Values only for request-scoped data that transits processes and // Use context Values only for request-scoped data that transits processes and
// APIs, not for passing optional parameters to functions. // APIs, not for passing optional parameters to functions.