From a9e6a96ac092cc5191d759488ee761e9a403ab8f Mon Sep 17 00:00:00 2001 From: Ian Lance Taylor Date: Sat, 17 Aug 2024 17:53:19 -0700 Subject: [PATCH] context: document that WithValue returns a derived context 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 Reviewed-by: Ian Lance Taylor Auto-Submit: Sameer Ajmani Commit-Queue: Ian Lance Taylor Auto-Submit: Ian Lance Taylor LUCI-TryBot-Result: Go LUCI --- src/context/context.go | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/context/context.go b/src/context/context.go index 763d4f777f..c960fda5f1 100644 --- a/src/context/context.go +++ b/src/context/context.go @@ -226,9 +226,10 @@ func TODO() Context { // After the first call, subsequent calls to a CancelFunc do nothing. type CancelFunc func() -// WithCancel returns a copy of parent with a new Done channel. The returned -// context's Done channel is closed when the returned cancel function is called -// or when the parent context's Done channel is closed, whichever happens first. +// WithCancel returns a derived context that points to the parent context +// but has a new Done channel. The returned context's Done channel is closed +// 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 // 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. // Calling [Cause] on the returned context returns nil. func WithoutCancel(parent Context) Context { @@ -599,12 +601,12 @@ func (c withoutCancelCtx) String() string { return contextName(c.c) + ".WithoutCancel" } -// WithDeadline returns a copy of the parent context with the deadline adjusted -// to be no later than d. If the parent's deadline is already earlier than d, -// WithDeadline(parent, d) is semantically equivalent to parent. The returned -// [Context.Done] channel is closed when the deadline expires, when the returned -// cancel function is called, or when the parent context's Done channel is -// closed, whichever happens first. +// WithDeadline returns a derived context that points to the parent context +// but has the deadline adjusted to be no later than d. If the parent's +// deadline is already earlier than d, WithDeadline(parent, d) is semantically +// equivalent to parent. The returned [Context.Done] channel is closed when +// the deadline expires, 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 // 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) } -// WithValue returns a copy of parent in which the value associated with key is -// val. +// WithValue returns a derived context that points to the parent Context. +// In the derived context, the value associated with key is val. // // Use context Values only for request-scoped data that transits processes and // APIs, not for passing optional parameters to functions. -- 2.48.1