context

Imports

Imports #

"errors"
"internal/reflectlite"
"sync"
"sync/atomic"
"time"

Constants & Variables

Canceled var #

Canceled is the error returned by [Context.Err] when the context is canceled for some reason other than its deadline passing.

var Canceled = *ast.CallExpr

DeadlineExceeded var #

DeadlineExceeded is the error returned by [Context.Err] when the context is canceled due to its deadline passing.

var DeadlineExceeded error = deadlineExceededError{...}

cancelCtxKey var #

&cancelCtxKey is the key that a cancelCtx returns itself for.

var cancelCtxKey int

closedchan var #

closedchan is a reusable closed channel.

var closedchan = *ast.CallExpr

goroutines var #

goroutines counts the number of goroutines ever created; for testing.

var goroutines atomic.Int32

Type Aliases

CancelCauseFunc type #

A CancelCauseFunc behaves like a [CancelFunc] but additionally sets the cancellation cause. This cause can be retrieved by calling [Cause] on the canceled Context or on any of its derived Contexts. If the context has already been canceled, CancelCauseFunc does not set the cause. For example, if childContext is derived from parentContext: - if parentContext is canceled with cause1 before childContext is canceled with cause2, then Cause(parentContext) == Cause(childContext) == cause1 - if childContext is canceled with cause2 before parentContext is canceled with cause1, then Cause(parentContext) == cause1 and Cause(childContext) == cause2

type CancelCauseFunc func(cause error)

CancelFunc type #

A CancelFunc tells an operation to abandon its work. A CancelFunc does not wait for the work to stop. A CancelFunc may be called by multiple goroutines simultaneously. After the first call, subsequent calls to a CancelFunc do nothing.

type CancelFunc func()

Interfaces

Context interface #

A Context carries a deadline, a cancellation signal, and other values across API boundaries. Context's methods may be called by multiple goroutines simultaneously.

type Context interface {
Deadline() (deadline time.Time, ok bool)
Done() <-chan struct{...}
Err() error
Value(key any) any
}

afterFuncer interface #

type afterFuncer interface {
AfterFunc(func()) func() bool
}

canceler interface #

A canceler is a context type that can be canceled directly. The implementations are *cancelCtx and *timerCtx.

type canceler interface {
cancel(removeFromParent bool, err error, cause error)
Done() <-chan struct{...}
}

stringer interface #

type stringer interface {
String() string
}

Structs

afterFuncCtx struct #

type afterFuncCtx struct {
cancelCtx
once sync.Once
f func()
}

backgroundCtx struct #

type backgroundCtx struct {
emptyCtx
}

cancelCtx struct #

A cancelCtx can be canceled. When canceled, it also cancels any children that implement canceler.

type cancelCtx struct {
Context
mu sync.Mutex
done atomic.Value
children map[canceler]struct{...}
err error
cause error
}

deadlineExceededError struct #

type deadlineExceededError struct {

}

emptyCtx struct #

An emptyCtx is never canceled, has no values, and has no deadline. It is the common base of backgroundCtx and todoCtx.

type emptyCtx struct {

}

stopCtx struct #

A stopCtx is used as the parent context of a cancelCtx when an AfterFunc has been registered with the parent. It holds the stop function used to unregister the AfterFunc.

type stopCtx struct {
Context
stop func() bool
}

timerCtx struct #

A timerCtx carries a timer and a deadline. It embeds a cancelCtx to implement Done and Err. It implements cancel by stopping its timer then delegating to cancelCtx.cancel.

type timerCtx struct {
cancelCtx
timer *time.Timer
deadline time.Time
}

todoCtx struct #

type todoCtx struct {
emptyCtx
}

valueCtx struct #

A valueCtx carries a key-value pair. It implements Value for that key and delegates all other calls to the embedded Context.

type valueCtx struct {
Context
key any
val any
}

withoutCancelCtx struct #

type withoutCancelCtx struct {
c Context
}

Functions

AfterFunc function #

AfterFunc arranges to call f in its own goroutine after ctx is canceled. If ctx is already canceled, AfterFunc calls f immediately in its own goroutine. Multiple calls to AfterFunc on a context operate independently; one does not replace another. Calling the returned stop function stops the association of ctx with f. It returns true if the call stopped f from being run. If stop returns false, either the context is canceled and f has been started in its own goroutine; or f was already stopped. The stop function does not wait for f to complete before returning. If the caller needs to know whether f is completed, it must coordinate with f explicitly. If ctx has a "AfterFunc(func()) func() bool" method, AfterFunc will use it to schedule the call.

func AfterFunc(ctx Context, f func()) (stop func() bool)

Background function #

Background returns a non-nil, empty [Context]. It is never canceled, has no values, and has no deadline. It is typically used by the main function, initialization, and tests, and as the top-level Context for incoming requests.

func Background() Context

Cause function #

Cause returns a non-nil error explaining why c was canceled. The first cancellation of c or one of its parents sets the cause. If that cancellation happened via a call to CancelCauseFunc(err), then [Cause] returns err. Otherwise Cause(c) returns the same value as c.Err(). Cause returns nil if c has not been canceled yet.

func Cause(c Context) error

Deadline method #

func (emptyCtx) Deadline() (deadline time.Time, ok bool)

Deadline method #

func (c *timerCtx) Deadline() (deadline time.Time, ok bool)

Deadline method #

func (withoutCancelCtx) Deadline() (deadline time.Time, ok bool)

Done method #

func (c *cancelCtx) Done() (<-chan struct{...})

Done method #

func (withoutCancelCtx) Done() (<-chan struct{...})

Done method #

func (emptyCtx) Done() (<-chan struct{...})

Err method #

func (emptyCtx) Err() error

Err method #

func (c *cancelCtx) Err() error

Err method #

func (withoutCancelCtx) Err() error

Error method #

func (deadlineExceededError) Error() string

String method #

func (c *cancelCtx) String() string

String method #

func (c *valueCtx) String() string

String method #

func (todoCtx) String() string

String method #

func (backgroundCtx) String() string

String method #

func (c *timerCtx) String() string

String method #

func (c withoutCancelCtx) String() string

TODO function #

TODO returns a non-nil, empty [Context]. Code should use context.TODO when it's unclear which Context to use or it is not yet available (because the surrounding function has not yet been extended to accept a Context parameter).

func TODO() Context

Temporary method #

func (deadlineExceededError) Temporary() bool

Timeout method #

func (deadlineExceededError) Timeout() bool

Value method #

func (emptyCtx) Value(key any) any

Value method #

func (c *cancelCtx) Value(key any) any

Value method #

func (c withoutCancelCtx) Value(key any) any

Value method #

func (c *valueCtx) Value(key any) any

WithCancel function #

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.

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)

WithCancelCause function #

WithCancelCause behaves like [WithCancel] but returns a [CancelCauseFunc] instead of a [CancelFunc]. Calling cancel with a non-nil error (the "cause") records that error in ctx; it can then be retrieved using Cause(ctx). Calling cancel with nil sets the cause to Canceled. Example use: ctx, cancel := context.WithCancelCause(parent) cancel(myError) ctx.Err() // returns context.Canceled context.Cause(ctx) // returns myError

func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc)

WithDeadline function #

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.

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)

WithDeadlineCause function #

WithDeadlineCause behaves like [WithDeadline] but also sets the cause of the returned Context when the deadline is exceeded. The returned [CancelFunc] does not set the cause.

func WithDeadlineCause(parent Context, d time.Time, cause error) (Context, CancelFunc)

WithTimeout function #

WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)). Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this [Context] complete: func slowOperationWithTimeout(ctx context.Context) (Result, error) { ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond) defer cancel() // releases resources if slowOperation completes before timeout elapses return slowOperation(ctx) }

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

WithTimeoutCause function #

WithTimeoutCause behaves like [WithTimeout] but also sets the cause of the returned Context when the timeout expires. The returned [CancelFunc] does not set the cause.

func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc)

WithValue function #

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. The provided key must be comparable and should not be of type string or any other built-in type to avoid collisions between packages using context. Users of WithValue should define their own types for keys. To avoid allocating when assigning to an interface{}, context keys often have concrete type struct{}. Alternatively, exported context key variables' static type should be a pointer or interface.

func WithValue(parent Context, key any, val any) Context

WithoutCancel function #

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

cancel method #

cancel closes c.done, cancels each of c's children, and, if removeFromParent is true, removes c from its parent's children. cancel sets c.cause to cause if this is the first time c is canceled.

func (c *cancelCtx) cancel(removeFromParent bool, err error, cause error)

cancel method #

func (a *afterFuncCtx) cancel(removeFromParent bool, err error, cause error)

cancel method #

func (c *timerCtx) cancel(removeFromParent bool, err error, cause error)

contextName function #

func contextName(c Context) string

init function #

func init()

parentCancelCtx function #

parentCancelCtx returns the underlying *cancelCtx for parent. It does this by looking up parent.Value(&cancelCtxKey) to find the innermost enclosing *cancelCtx and then checking whether parent.Done() matches that *cancelCtx. (If not, the *cancelCtx has been wrapped in a custom implementation providing a different done channel, in which case we should not bypass it.)

func parentCancelCtx(parent Context) (*cancelCtx, bool)

propagateCancel method #

propagateCancel arranges for child to be canceled when parent is. It sets the parent context of cancelCtx.

func (c *cancelCtx) propagateCancel(parent Context, child canceler)

removeChild function #

removeChild removes a context from its parent.

func removeChild(parent Context, child canceler)

stringify function #

stringify tries a bit to stringify v, without using fmt, since we don't want context depending on the unicode tables. This is only used by *valueCtx.String().

func stringify(v any) string

value function #

func value(c Context, key any) any

withCancel function #

func withCancel(parent Context) *cancelCtx

Generated with Arrow