Skip to content

std::context

The execution context an application carries in a field of its app struct: a deadline and values scoped to one request or run (Program execution). The module’s entire public surface is the opaque Context type with inherent functions, so every call is type-qualified (Context.deadline(c)); there are no file-level functions.

with_deadline takes an absolute Instant; with_timeout sets a deadline at now() + dur. Both return a new Context. Deadlines flow from parent to child and only tighten: the earliest deadline anywhere along the chain is the one in force, so a child can bound its own work and can never loosen the bound it inherited.

There is no cancellation predicate on the surface. A task stopping is not a state its body reads, because the runtime consults the task’s cancellation at every safe point and unwinds the task there, ahead of any check the body could run.

Import with import std::context.

Types

type Context

Per-life execution context, threaded by the runtime through every call stack. An application that wants one builds it in boot with Context.root() and returns it in a field of the application struct, read as MyApp.context (whatever the field is named). with MyApp.context = Context.with_X(MyApp.context, ...) derives a child context from that line to the end of the enclosing block.

Opaque: user code cannot construct a Context value directly. Only Context.root(), the language runtime, and the Context.with_* derivers produce them.

fn root() -> Context

type function on Context

Construct a root Context: no deadline, no values and no parent. A boot that wants a context field builds it with this, or with a child derived from it (Context.with_timeout(Context.root(), d)).

root = Context.root()
assert Context.deadline(root) == Maybe.None
fn deadline(c: Context) -> Maybe<Instant>

type function on Context

Absolute deadline of this context, if any.

assert Context.deadline(Context.root()) == Maybe.None
fn deadline_remaining(c: Context) -> Maybe<Duration>

type function on Context

Time until the deadline, if there is one. None means no deadline is set; a Duration of zero means it has passed.

assert Context.deadline_remaining(Context.root()) == Maybe.None
fn with_deadline(c: Context, at: Instant) -> Context

type function on Context

Child context with deadline at at. If the parent has a tighter deadline already, the parent’s deadline stays in force. The clock counts a deadline in 64 bits of nanoseconds, so one past the year 2262 is clamped to the latest it counts, which no program reaches, and one before 1677 to the earliest, which has passed.

child = Context.with_deadline(Context.root(), Instant.from_seconds(0))
assert Context.deadline_remaining(child) == Maybe.Some(Duration.seconds(0))
fn with_timeout(c: Context, dur: Duration) -> Context

type function on Context

Child context with deadline at now() + dur. If the parent has a tighter deadline already, the parent’s deadline wins. A zero or negative dur makes a context whose deadline has already passed. A deadline past the year 2262, the latest the clock counts, is that latest moment, which no program reaches.

child = Context.with_timeout(Context.root(), Duration.seconds(-1))
assert Context.deadline_remaining(child) == Maybe.Some(Duration.seconds(0))

never = Context.with_timeout(Context.root(), Duration.hours(1_000_000_000))
assert Context.deadline(never) == Maybe.Some(Instant.from_nanos(9_223_372_036_854_775_807))
fn with_value<T>(c: Context, value: T) -> Context

type function on Context

Return a child context with value stored under its Nomi type.

Context values are intended for request- or execution-scoped metadata such as trace IDs, auth subjects, or request IDs. Prefer explicit app fields (MyApp.store, MyApp.logger) for dependencies, and prefer domain types (TraceId, Subject) over raw scalars.

type TraceId String
traced = Context.with_value(Context.root(), TraceId("trace-123"))
assert Context.value(traced, TraceId) == Maybe.Some(TraceId("trace-123"))
fn value<T>(c: Context, value_type: Type<T>) -> Maybe<T>

type function on Context

Look up the nearest value of type T, walking through parent contexts when this context has not overridden that type.

Context.value(context, TraceId)
type TraceId String
root = Context.root()
assert Context.value(root, TraceId) == Maybe.None

impl Debug for Context

fn inspect(value: Context) -> String

impl Debug.inspect