Documentation
¶
Overview ¶
Package chordctx ports packages/chord/src/context/index.ts (`@earendil-works/chord/context`) onto context.Context. A chord Context is a Go context: an abort signal is cancellation, with the abort reason carried as the cancellation cause, and `toString` is the context's String method, which prints Pi's text. Background and the placeholder root are Pi's BACKGROUND_CONTEXT and TODO_CONTEXT roots; contexts derived from them by this package print as Pi's contexts do. A context derived from another root, such as context.Background, prints that root's own text first.
Index ¶
- func Await[T any](ctx context.Context, work <-chan Settled[T]) (T, error)
- func Background() context.Context
- func TODO() context.Context
- func Telemetry(ctx context.Context) telemetry.TelemetrySpan
- func TraceIn[T any](ctx context.Context, options telemetry.SpanOptions, ...) (T, error)
- func Value[T any](ctx context.Context, key Key[T]) (T, bool)
- func WithAbortSignal(parent, signal context.Context) context.Context
- func WithCancel(parent context.Context) (ctx context.Context, cancel func(cause error))
- func WithTelemetry(parent context.Context, t telemetry.TelemetrySpan) context.Context
- func WithValue[T any](parent context.Context, key Key[T], value T) context.Context
- func WithoutAbortSignal(parent context.Context) context.Context
- type Key
- type Settled
- type Token
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Await ¶
Await observes work until it settles or the invocation is cancelled. Cancellation returns the cancellation cause from this waiter only; it does not cancel the work, which may still settle later. A nil ctx waits for the work alone.
func Background ¶
Background is Pi's BACKGROUND_CONTEXT: the root context of work that has no caller.
func TODO ¶
This function is Pi's TODO_CONTEXT: a root context for code that has no context to receive yet. It is distinct from Background.
func Telemetry ¶
func Telemetry(ctx context.Context) telemetry.TelemetrySpan
Telemetry is Pi's `Context.telemetry`: the explicit telemetry parent of ctx, always a span (the no-op span is one), so a caller never narrows it. It is never nil: a context that carries none, context.Background() and the to-do context included, returns telemetry.NoopTelemetryContext, as Pi's BaseContext defaults to NOOP_TELEMETRY_CONTEXT. Pi's Context is a closed interface that custom implementations must extend with a `telemetry: TelemetrySpan` member (a Breaking Change upstream, whose type narrowed from TelemetryContext when Context.telemetry became always a span, so withTelemetry accepts spans and not adapters). A Go context is stdlib's open interface, so a context from outside this package carries no telemetry and reads as the no-op parent; no Go caller breaks.
func TraceIn ¶
func TraceIn[T any](ctx context.Context, options telemetry.SpanOptions, fn func(child context.Context) (T, error)) (T, error)
TraceIn runs a child span of Telemetry(ctx) and passes fn a derived context whose telemetry is that span: Pi's traceIn. It returns fn's result, and fn's error as the identical value, after the span ends, as telemetry.StartSpan does. Pi's callback receives one `Context & { telemetry: TelemetrySpan }`, narrowed by the type system. Go cannot narrow a context's type, so the callback receives the context and reads the span as Telemetry(child), which is always a span.
func WithAbortSignal ¶
WithAbortSignal derives a context cancelled by either the parent or signal, whichever is first, with that one's cause. The parent is unchanged. A signal that is already cancelled cancels the result before it is returned, as AbortSignal.any does with an aborted input.
func WithCancel ¶
WithCancel derives an independently cancellable child. cancel records cause, and a nil cause records context.Canceled.
func WithTelemetry ¶
WithTelemetry derives an explicit telemetry parent without changing cancellation or application values: it is Pi's withTelemetry. The parent is unchanged, and a context derived from the result by this package keeps the telemetry until another WithTelemetry replaces it. Pi types the result as `Context & { telemetry: T }` for the concrete T it was given; Go has no intersection type, so a caller that needs the concrete T keeps its own reference, and Telemetry(result) is the TelemetryContext interface. The argument order is the parent first, as WithValue and WithAbortSignal take it; Pi takes the telemetry first.
Types ¶
type Key ¶
type Key[T any] struct { // contains filtered or unexported fields }
Key is the typed identity of one value carried by a context. Two keys never collide, even with equal descriptions or types.
func (Key[T]) Description ¶
Description is the name given to NewKey.
type Token ¶
type Token struct {
// contains filtered or unexported fields
}
Token is ContextKey.token in Pi: the identity of a key. Two tokens are equal exactly when they are the token of the same key, and the description is the one the key was created with, as `token.description` is.
func (Token) Description ¶
Description is the name given to the key the token belongs to.