chordctx

package
v0.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Await

func Await[T any](ctx context.Context, work <-chan Settled[T]) (T, error)

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

func Background() context.Context

Background is Pi's BACKGROUND_CONTEXT: the root context of work that has no caller.

func TODO

func TODO() context.Context

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 Value

func Value[T any](ctx context.Context, key Key[T]) (T, bool)

Value returns the value stored under key and whether one exists.

func WithAbortSignal

func WithAbortSignal(parent, signal context.Context) context.Context

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

func WithCancel(parent context.Context) (ctx context.Context, cancel func(cause error))

WithCancel derives an independently cancellable child. cancel records cause, and a nil cause records context.Canceled.

func WithTelemetry

func WithTelemetry(parent context.Context, t telemetry.TelemetrySpan) context.Context

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.

func WithValue

func WithValue[T any](parent context.Context, key Key[T], value T) context.Context

WithValue derives a context containing one additional or replaced value. The parent is unchanged.

func WithoutAbortSignal

func WithoutAbortSignal(parent context.Context) context.Context

WithoutAbortSignal derives a context that keeps every value but ignores caller cancellation. It is for mandatory cleanup only.

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 NewKey

func NewKey[T any](description string) Key[T]

NewKey creates a key. The description names it in diagnostics only.

func (Key[T]) Description

func (key Key[T]) Description() string

Description is the name given to NewKey.

func (Key[T]) Token

func (key Key[T]) Token() Token

Token is the key's identity: the value a context stores a key's value under.

type Settled

type Settled[T any] struct {
	Value T
	Err   error
}

Settled is the outcome of a unit of work: the Go form of a settled promise.

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

func (token Token) Description() string

Description is the name given to the key the token belongs to.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL