Documentation
¶
Overview ¶
Package contextutil provides context lifecycle helpers shared by transports and middleware.
Index ¶
- func EffectiveError(ctx context.Context) error
- func PinnedValue(ctx context.Context, key any) (any, bool)
- func TryPinValue(ctx context.Context, key, value any) bool
- func TrySetValueProvider(ctx context.Context, provider ValueProvider) bool
- func TryUpdatePinnedValueLocked[T comparable](ctx context.Context, key any, old T, update func() T) (T, bool)
- type LazyDeadline
- type ValueProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EffectiveError ¶
EffectiveError reports a context cancellation even at the narrow deadline boundary where the wall clock has reached Deadline but the context timer goroutine has not yet published Err. This matters after a socket operation: the kernel deadline can return first, and treating that I/O timeout as upstream evidence would leak a request-local failure into shared state.
func PinnedValue ¶
PinnedValue returns the exact value stored in the LazyDeadline's request-lifetime slot. Unlike ctx.Value, it never falls through to a value provider or parent context.
func TryPinValue ¶
TryPinValue stores one internal request-lifetime control value directly on the LazyDeadline reachable through ctx. The pin survives pooled metadata reuse without allocating a context.WithValue node. It is deliberately not exposed through Context.Value: callers must use PinnedValue, keeping the ordinary context value chain immutable. A second distinct pin fails.
func TrySetValueProvider ¶
func TrySetValueProvider(ctx context.Context, provider ValueProvider) bool
TrySetValueProvider installs provider directly on the LazyDeadline reachable through ctx. It returns false for ordinary contexts or when a provider was already installed.
func TryUpdatePinnedValueLocked ¶
func TryUpdatePinnedValueLocked[T comparable]( ctx context.Context, key any, old T, update func() T, ) (T, bool)
TryUpdatePinnedValueLocked computes and installs a replacement while holding the LazyDeadline's request-lifetime lock. It is intended for transitions whose initialization must complete before a concurrent request owner can close and recycle adjacent pooled state.
update must be bounded and must not call the pin mutation APIs recursively on ctx (or a context derived from it): pinMu is deliberately non-reentrant. Cancellation methods use a separate lock, so update may safely inspect Done, Err or context.AfterFunc. The Locked suffix exposes the callback contract at each call site.
Types ¶
type LazyDeadline ¶
type LazyDeadline struct {
// contains filtered or unexported fields
}
LazyDeadline is a request context whose absolute deadline is visible immediately, but whose timer and parent-cancellation registration are materialized only when a caller needs Done or AfterFunc.
This keeps terminal cache hits off context.WithDeadline's allocation path while preserving the same deadline for cache misses, child contexts and blocking transport operations. A LazyDeadline must not be reused across requests: child contexts and cancellation callbacks may retain it.
func WithLazyDeadline ¶
func WithLazyDeadline(parent context.Context, deadline time.Time) *LazyDeadline
WithLazyDeadline returns a LazyDeadline with the earlier of deadline and the parent's deadline. Call Cancel when the request finishes.
func WithLazyTimeout ¶
func WithLazyTimeout(parent context.Context, timeout time.Duration) *LazyDeadline
WithLazyTimeout returns a LazyDeadline whose deadline is no later than the parent's. Call Cancel when the request finishes.
func (*LazyDeadline) Cancel ¶
func (c *LazyDeadline) Cancel()
Cancel releases an armed timer/parent registration, or records a terminal cause without arming one when the request completed on the fast path.
func (*LazyDeadline) Deadline ¶
func (c *LazyDeadline) Deadline() (time.Time, bool)
Deadline implements context.Context.
func (*LazyDeadline) Done ¶
func (c *LazyDeadline) Done() <-chan struct{}
Done implements context.Context. Its first live call materializes the standard-library deadline context so timer and parent cancellation semantics remain identical on paths that actually block.
func (*LazyDeadline) Err ¶
func (c *LazyDeadline) Err() error
Err implements context.Context. A parent cancellation or elapsed deadline materializes the standard context to pin the first terminal cause.
func (*LazyDeadline) Value ¶
func (c *LazyDeadline) Value(key any) any
Value implements context.Context. Once materialized, values are deliberately routed through the standard child context. Besides preserving values, this lets context.WithCancel/WithDeadline recognize its private parent fast path instead of spawning a propagation goroutine.
type ValueProvider ¶
ValueProvider supplies request-local context values without adding another context.WithValue wrapper to a LazyDeadline. Providers are installed before the context is published to middleware and must be safe for concurrent use.
Source Files