chordctx

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 7 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 AbortOrder

func AbortOrder(ctx context.Context) uint64

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

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. 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

func Background() context.Context

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

func Receive

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

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

func StepBatch(ctx context.Context, key any, item func(), flush func(items []func())) bool

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

func Suspend(ctx context.Context)

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

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. 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

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 WithStep

func WithStep(parent context.Context) (context.Context, func())

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

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