lib/context.x
Bounded runtime state and value export.
Primary API
| Function | Summary |
|---|---|
Context.close | Closes the current Context, reclaims unexported state, and restores parent. |
Context.current | Returns the Context currently active on this thread, or NULL. |
Context.export | Exports value into the parent of the current Context. |
Context.open | Opens and makes current a Context using the active canonical-value pool. |
Context.open_isolated | Opens and makes current a Context with a private canonical-value pool. |
Context.open_isolated_named | Opens and makes current a named Context with a private canonical pool. |
Context.open_named | Opens and makes current a named Context that inherits immutable values. |
Context
Context.close
void Context.close(Context context)
Closes the current Context, reclaims unexported state, and restores
parent.
The Context must be current; all pointers into its remaining Scope or
private canonical pool become invalid.
Raises: <bad-state> for a null or noncurrent Context, or while its
Match
cache has an active lease. The failure leaves the Context active.
Source: lib/context.x:348
Context.current
Context Context.current(void)
Returns the Context currently active on this thread, or NULL.
Source: lib/context.x:175
Context.export
Var Context.export(Context context, Var value)
Exports value into the parent of the current Context.
Built-in movable families preserve identity. A custom exact-descriptor
exporter defines its returned value, including identity. Private canonical
immutable built-ins may change, so callers must use the returned value;
inherited or borrowed built-ins are unchanged. void exports as void
because it owns no storage.
Built-in Array and Map export restores the container’s source ownership
if recursive export fails, but nested exports already completed are not
rolled back.
Raises: <bad-state> unless context is current, <bad-types> for an
unsupported value without a registered exporter, or a cause from nested
allocation, hashing, equality, or custom export.
Source: lib/context.x:309
Context.open
Context Context.open(void)
Opens and makes current a Context using the active canonical-value pool.
Close it before its parent; its Scope owns subsequent mutable
allocations.
Raises: <alloc-fail> or <size-limit> while constructing nested state.
Failed construction restores the parent’s Scope, canonical pool, Error,
Match, and current Context state.
Source: lib/context.x:146
Context.open_isolated
Context Context.open_isolated(void)
Opens and makes current a Context with a private canonical-value pool.
Export surviving immutable values before closing the Context.
Raises: <alloc-fail> or <size-limit> while constructing nested state.
Failed construction restores the parent’s Scope, canonical pool, Error,
Match, and current Context state.
Source: lib/context.x:163
Context.open_isolated_named
Context Context.open_isolated_named(const char *name)
Opens and makes current a named Context with a private canonical pool.
The diagnostic name is copied; export survivors before closing the
Context.
Raises: <alloc-fail> or <size-limit> while constructing nested state.
Failed construction restores the parent’s Scope, canonical pool, Error,
Match, and current Context state.
Source: lib/context.x:172
Context.open_named
Context Context.open_named(const char *name)
Opens and makes current a named Context that inherits immutable values.
The diagnostic name is copied, and the Context must close before its
parent.
Raises: <alloc-fail> or <size-limit> while constructing nested state.
Failed construction restores the parent’s Scope, canonical pool, Error,
Match, and current Context state.
Source: lib/context.x:155
Advanced and interop API
| Function | Summary |
|---|---|
Context.move_allocation | Moves one custom-exporter-owned allocation to the destination Context. |
Context.owns | Reports whether allocation belongs to context’s Scope chain. |
Context
Context.move_allocation
void Context.move_allocation(Context context, void *allocation)
Moves one custom-exporter-owned allocation to the destination Context.
A null allocation or one outside context’s Scope chain is unchanged.
Application code exports its value with Context.export instead.
Source: lib/context.x:100
Context.owns
int Context.owns(Context context, void *allocation)
Reports whether allocation belongs to context’s Scope chain.
The nonnull pointer must come from a Scope allocator. Registered custom
exporters call this before moving their own storage.
Source: lib/context.x:86
Runtime-internal callables
These callables connect runtime translation units. They are documented for source readers but are not supported as user API.
| Function | Summary |
|---|---|
Context.export_destination | Returns the borrowed Scope slot that receives exports from context. |
Context.export_nested | Recursively exports one nested value through an active or sealed Context. |
Context.export_scope | Exports a sealed worker result Scope into the current Scope and pool. |
Context.initialize | Registers Context cleanup before workers can start. |
Context
Context.export_destination
Scope *Context.export_destination(Context context)
Returns the borrowed Scope slot that receives exports from context.
The slot remains valid only while the Context’s destination state lives;
a null Context returns NULL.
Source: lib/context.x:93
Context.export_nested
Var Context.export_nested(Context context, Var value)
Recursively exports one nested value through an active or sealed Context.
Registered custom exporters call this; other callers export their
complete result with Context.export. Built-in movable families preserve
identity. A custom exact-descriptor exporter defines its returned value,
including identity. For built-ins, private canonical pointers may change,
so callers must use the result; inherited or borrowed values are unchanged.
Built-in Array and Map export restores the container’s source ownership
if recursive export fails, but nested exports already completed are not
rolled back.
Raises: <bad-types> for an unsupported value without a registered
exporter, or a cause from nested allocation, hashing, equality, or custom
export.
Source: lib/context.x:192
Context.export_scope
Var Context.export_scope(Scope source_scope, Pool pool, Var value)
Exports a sealed worker result Scope into the current Scope and pool.
Built-in movable families preserve identity. A custom exact-descriptor
exporter defines its returned value, including identity. Private canonical
built-ins may change, so callers must use the returned value; inherited or
borrowed built-ins are unchanged. The source Scope and pool remain
caller-owned through the call.
Built-in Array and Map export restores the container’s source ownership
if recursive export fails, but nested exports already completed are not
rolled back.
Raises: <bad-types> for an unsupported value without a registered
exporter, or a cause from nested allocation, hashing, equality, or custom
export.
Source: lib/context.x:330
Context.initialize
void Context.initialize(void)
Registers Context cleanup before workers can start.
Source: lib/context.x:68
Design notes
Context combines one Scope lifetime with Error and Match state. An
isolated Context also owns a nested canonical-value pool. Export moves
built-in movable storage owned by the source Scope. For built-in
immutable
values, it recanonicalizes only those owned by the source’s private pool;
inherited or borrowed values are returned unchanged. Closing reclaims
everything else.
Tests and examples
make verify (unittest/test-context.x).