context

import "context"

Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes. Incoming requests to a server should create a [Context], and outgoing calls to servers should accept a Context. The chain of function calls between them must propagate the Context, optionally replacing it with a derived Context created using [WithCancel], [WithDeadline], [WithTimeout], or [WithValue]. A Context may be canceled ...

Go 1.26.1

Variables

var Canceled = errors.New("context canceled")

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

context/context.go:167

var DeadlineExceeded error = deadlineExceededError{}

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

context/context.go:171

Functions

func AfterFunc(ctx Context, f func(...)) func(...)

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 stoppe...

context/context.go:325

func Background() Context

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.

context/context.go:215

func Cause(c Context) error

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.

context/context.go:288

func TODO() Context

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).

context/context.go:223

func WithCancel(parent Context) (Context, CancelFunc)

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.

context/context.go:240

func WithCancelCause(parent Context) (Context, CancelCauseFunc)

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

context/context.go:268

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

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

context/context.go:625

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

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.

context/context.go:632

func WithoutCancel(parent Context) Context

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.

context/context.go:585

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

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) }

context/context.go:703

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

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.

context/context.go:710

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

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 whe...

context/context.go:727

Types

type CancelCauseFunc func(cause error)

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

context/context.go:255

type CancelFunc func()

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.

context/context.go:231

type Context interface {
	// Deadline returns the time when work done on behalf of this context
	// should be canceled. Deadline returns ok==false when no deadline is
	// set. Successive calls to D...

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

context/context.go:71