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 AbortOrder(ctx context.Context) uint64
- func Await[T any](ctx context.Context, work <-chan Settled[T]) (T, error)
- func Background() context.Context
- func Receive[T any](ctx context.Context, work <-chan T) (T, error)
- func StepBatch(ctx context.Context, key any, item func(), flush func(items []func())) bool
- func Suspend(ctx 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 WithStep(parent context.Context) (context.Context, func())
- 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 AbortOrder ¶
AbortOrder is when ctx was aborted relative to other contexts of this package: the number of the earliest abort that ended it (its own cancel, or the one of a parent or signal it derives from), 0 for a context not aborted by this package's cancel functions. AbortSignal.any takes the reason of the source that aborted first; a Go context derived from two sources is cancelled by listeners on goroutines of their own, which may run in any order, so the one that decides the reason compares AbortOrder of the sources instead.
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. A method handler's ctx parks the handler where it starts to wait: Pi runs an async handler synchronously up to its first `await` inside the section that admits its call, and the Go handler is blocking code that parks at the first wait of a host primitive or of Await or Receive. Code that waits for something else (a raw channel receive, a mutex) is a synchronous block of the section, as a synchronous loop is in Pi.
func Background ¶
Background is Pi's BACKGROUND_CONTEXT: the root context of work that has no caller.
func Receive ¶
Receive is Await for a plain channel: `await promise` of work that cannot reject, as a gate a test resolves. It returns the received value, or the cancellation cause of ctx from this waiter only. A closed channel yields the zero value, as a resolved promise of nothing. A nil ctx waits for the channel alone.
func StepBatch ¶
StepBatch leaves item in the step ctx carries, under key, and reports whether it did: false when ctx carries no step or its step ended, and the caller then runs the item itself. All items under one key reach the flush of the first of them together, in order, when the step ends. key must be comparable.
func Suspend ¶
Suspend is the first suspension of a method handler: Pi runs an async handler synchronously, inside the section that admits its call, up to its first `await`, and the rest of that section waits for it. A Go handler is blocking code that runs as a coroutine of the section's goroutine, and the section waits until it returns or suspends. The host primitives that wait (Get, Call, Sleep, UntilAborted, transactions, Await, Receive) suspend the handler themselves; call Suspend with the handler's ctx, or a context derived from it, right before waiting for anything else (a channel, a condition, I/O that another goroutine of the host's section must not outwait). Code that waits without suspending is a synchronous block of the section, as a synchronous loop is in Pi: the host's other work does not run until it ends. Suspend of a context that carries no handler does nothing, and a second call does nothing. Only the handler's own goroutine suspends it: a goroutine the handler started leaves the handler's synchronous part to the handler's own next wait, whatever it waits for itself, as an `await` inside async work that Pi's handler started and did not await does.
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. A parent with no cancellation (no Done channel) leaves signal alone to cancel: Pi's `withAbortSignal` then uses signal itself, with no listener, and so does the result here (signalContext), which registers nothing on signal, so a signal that outlives its derived contexts (an attempt's, a reference's) keeps nothing of them.
func WithCancel ¶
WithCancel derives an independently cancellable child. cancel records cause, and a nil cause records context.Canceled.
func WithStep ¶
WithStep derives a context that carries a new step, and the function that ends it: end hands every group its items, in the order they were left, through the flush of the group's first item (a group's flush may start further work, but leaves nothing in this step any more). end is idempotent; items left after it are refused. A nested step is its own.
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.