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.
Exports
Section titled “Exports”Types
type Context
Section titled “type Context”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.
Context.root
Section titled “Context.root”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
Context.deadline
Section titled “Context.deadline”fn deadline(c: Context) -> Maybe<Instant>
type function on Context
Absolute deadline of this context, if any.
assert Context.deadline(Context.root()) == Maybe.None
Context.deadline_remaining
Section titled “Context.deadline_remaining”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
Context.with_deadline
Section titled “Context.with_deadline”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))
Context.with_timeout
Section titled “Context.with_timeout”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))
Context.with_value
Section titled “Context.with_value”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"))
Context.value
Section titled “Context.value”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
Context.inspect
Section titled “Context.inspect”impl Debug for Context
fn inspect(value: Context) -> String
impl Debug.inspect