Documentation
¶
Overview ¶
Package context provides small wrappers and aliases around the standard library context package.
The primary purpose of this package is to offer a stable go-service import path for commonly used context primitives while preserving the exact semantics of the standard library context package.
Most identifiers are thin aliases/wrappers around context (for example Context, CancelFunc, CancelCauseFunc, Background, WithDeadline, WithTimeout, Cause, and WithValue). They exist so packages within go-service and downstream services can consistently import github.com/alexfalkowski/go-service/v2/context without mixing direct stdlib imports across the codebase.
Cause-aware APIs mirror the standard library behavior: [Context.Err] continues to report the standard sentinels (Canceled or DeadlineExceeded), while Cause can expose a richer diagnostic error when a cause-aware constructor was used. WithoutCancel is the detaching exception: it preserves parent values but drops the parent deadline, Done channel, Err state, and cancellation cause.
This package also defines Key, a typed helper for context value keys to reduce accidental collisions when multiple packages store values in the same context.
Index ¶
- Variables
- func Cause(ctx Context) error
- func WithCancel(parent Context) (Context, CancelFunc)
- func WithCancelCause(parent Context) (Context, CancelCauseFunc)
- func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
- func WithDeadlineCause(parent Context, d time.Time, cause error) (Context, CancelFunc)
- func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
- func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc)
- type CancelCauseFunc
- type CancelFunc
- type Context
- type Key
Constants ¶
This section is empty.
Variables ¶
var Canceled = context.Canceled
Canceled is an alias for context.Canceled.
It is returned by [Context.Err] when the context is canceled.
var DeadlineExceeded = context.DeadlineExceeded
DeadlineExceeded is an alias for context.DeadlineExceeded.
It is returned by [Context.Err] when the context deadline passes. When a cause-aware deadline or timeout API is used, Cause can expose a richer diagnostic error while Err still reports DeadlineExceeded.
Functions ¶
func Cause ¶ added in v2.343.0
Cause returns the reason a context was canceled.
This is a thin wrapper around context.Cause. Cause returns nil until the context is canceled. When a cause-aware API is used, Cause can expose a more specific diagnostic error while Err still reports the standard cancellation sentinel. For a context returned by WithoutCancel, Cause always returns nil because the detached context does not inherit cancellation from its parent.
func WithCancel ¶ added in v2.326.1
func WithCancel(parent Context) (Context, CancelFunc)
WithCancel returns a derived context that points to the parent context but has a new Done channel.
This is a thin wrapper around context.WithCancel. The returned CancelFunc should be called to release resources associated with the derived context.
func WithCancelCause ¶ added in v2.343.0
func WithCancelCause(parent Context) (Context, CancelCauseFunc)
WithCancelCause returns a derived context that points to the parent context and records an optional cause.
This is a thin wrapper around context.WithCancelCause. [Context.Err] still reports Canceled, while Cause returns the provided diagnostic error (or Canceled when cancel is called with nil).
func WithDeadline ¶
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
WithDeadline returns a copy of parent with the deadline adjusted to be no later than d.
This is a thin wrapper around context.WithDeadline. The returned CancelFunc should be called to release resources associated with the derived context.
func WithDeadlineCause ¶ added in v2.343.0
WithDeadlineCause returns a copy of parent with the deadline adjusted to be no later than d.
This is a thin wrapper around context.WithDeadlineCause. If the deadline expires, Err reports DeadlineExceeded while Cause returns the configured diagnostic error. Calling the returned CancelFunc directly cancels the context without setting the configured cause.
func WithTimeout ¶
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
WithTimeout returns a copy of parent with a timeout applied.
This is a thin wrapper around context.WithTimeout. The returned CancelFunc should be called to release resources associated with the derived context.
func WithTimeoutCause ¶ added in v2.343.0
WithTimeoutCause returns a copy of parent with a timeout applied.
This is a thin wrapper around context.WithTimeoutCause. If the timeout expires, Err reports DeadlineExceeded while Cause returns the configured diagnostic error. Calling the returned CancelFunc directly cancels the context without setting the configured cause.
Types ¶
type CancelCauseFunc ¶ added in v2.343.0
type CancelCauseFunc = context.CancelCauseFunc
CancelCauseFunc is an alias for context.CancelCauseFunc.
It cancels a Context created by WithCancelCause and records the provided cause. [Context.Err] still reports context.Canceled, while Cause exposes the richer diagnostic error.
type CancelFunc ¶
type CancelFunc = context.CancelFunc
CancelFunc is an alias for context.CancelFunc.
It cancels a Context created by WithCancel, WithDeadline, or WithTimeout, releasing resources associated with it. As with the standard library, you should call the returned CancelFunc as soon as the operations running in the derived context complete.
type Context ¶
Context is an alias for context.Context.
It carries deadlines, cancellation signals, and request-scoped values across API boundaries. The semantics are identical to the standard library context package.
func Background ¶
func Background() Context
Background returns an empty, non-cancelable context.
This is a thin wrapper around context.Background. Use it as the top-level parent for main, initialization, and tests. Request handlers should typically use the request-provided context instead.
func WithValue ¶
WithValue returns a copy of parent in which the value associated with key is val.
This is a thin wrapper around context.WithValue.
Best practice: use context values only for request-scoped data that transits process boundaries (like trace IDs). Do not use them to pass optional parameters to functions.
func WithoutCancel ¶ added in v2.326.3
WithoutCancel returns a copy of parent that is not canceled when parent is canceled.
This is a thin wrapper around context.WithoutCancel. The returned context still exposes values from parent, but it has no deadline, no Done channel, Err always reports nil, and Cause always returns nil.
type Key ¶
type Key string
Key is a typed helper for storing values in a context.
Using a distinct key type reduces accidental collisions when multiple packages store values in the same context. Prefer defining keys as unexported package variables, for example:
var userIDKey context.Key = "user_id"
and retrieving values with type assertions at the call site.
Source Files