Documentation
¶
Overview ¶
Go programmers often use contexts to store request-scoped information, especially metadata or log fields. In general, these are singletons per type: it doesn't make sense for a context to have multiple IDs, origins, or loggers. The functions in this package provide a simple and useful API for working with contexts in this way.
QUICK START ¶
Save and retrieve values from a context:
ctx := ectx.WithValue(context.Background(), zap.L().With(zap.String("author", "efron")))
Get a value from the context:
log, ok := ectx.Val[*zap.Logger](ctx)
Get a value from a context, using a default if it's missing
log := ectx.Val(ctx, log.Default())
Get a value from a context, or call the provided function if it's missing
log := ectx.ValOr(ctx, log.Default) // note the missing ()
Word of warning ¶
The context is often misused as a general-purpose key-value storage, which causes a ton of harm. This ectx's api _deliberately omits_ the more general context.WithValue to discourage this. Ask yourself two questions before putting a value in the context rather than passing it directly as a value in the function signature.
1: Is this PART of the function, or is it ABOUT the function?
2: Should the function proceed without the value (i.e, through a sensible default or no-op?)
Only if both are true should you use ectx. When in doubt, error on the side of injecting dependencies directly.
Index ¶
- func Background() context.Context
- func MustVal[T any](ctx context.Context) T
- func StripCancel(ctx context.Context) context.Context
- func TODO() context.Context
- func Val[T any](ctx context.Context) (T, bool)
- func ValOr[T any](ctx context.Context, fallback T) T
- func ValOrElse[T any](ctx context.Context, f func() T) T
- func ValOrZero[T any](ctx context.Context) T
- func WithCancel(parent context.Context) (ctx context.Context, cancel context.CancelFunc)
- func WithDeadline(parent context.Context, deadline time.Time) (ctx context.Context, cancel context.CancelFunc)
- func WithTimeout(parent context.Context, timeout time.Duration) (ctx context.Context, cancel context.CancelFunc)
- func WithVal[T any](ctx context.Context, t T) context.Context
- type TypeKey
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Background ¶
// alias for context.Background
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 MustVal ¶
MustVal gets the entry stored under TypeKey[T], panicking otherwise.
Warning ¶
Be careful when and where you use this function! Anything you MUST have should probably be in the function signature, not the context. This can be useful for tests & in rare other occasions and is included for completion.
func StripCancel ¶
StripCancel returns a context which inherits it's parents values, but NOT it's deadline or cancellation.
func TODO ¶
// alias for context.TODO()
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 ValOr ¶
ValOr gets the entry stored under TypeKey[T], if it exists, returning fallback otherwise.
func WithCancel ¶
// alias for context.WithCancel 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. 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 ¶
func WithDeadline(parent context.Context, deadline time.Time) (ctx context.Context, cancel context.CancelFunc)
// alias for context.WithDeadline
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's 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 WithTimeout ¶
func WithTimeout(parent context.Context, timeout time.Duration) (ctx context.Context, cancel context.CancelFunc)
// alias for context.WithTimeout
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:
Source Files