lib/context.x
Bounded runtime state and value export.
Primary API
| Function | Summary |
|---|---|
Context.cleanup | Ends the owned lifetime when a managed local leaves its block. |
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.cleanup
meta native void Context.cleanup(Context value)
Ends the owned lifetime when a managed local leaves its block.
Source: lib/context.x:355
Context.close
meta native void Context.close(Context c)
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:331
Context.current
meta native Context Context.current(void)
Returns the Context currently active on this thread, or NULL.
Source: lib/context.x:321
Context.export
meta native Var Context.export(Context context, Var value)
Exports value into the parent of the current Context.
Values may belong to a retained region of that Context; export them
while live, before releasing their Scope or closing the 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:72
Context.open
meta native 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:258
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:275
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:284
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:267
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 c, void *allocation)
Moves one custom-exporter-owned allocation to the destination Context.
A null allocation or one outside c’s Scope chain is unchanged.
Application code exports its value with Context.export instead.
Source: lib/context.x:245
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:225
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 c. |
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 c)
Returns the borrowed Scope slot that receives exports from c.
The slot remains valid only while the Context’s destination state lives;
a null Context returns NULL.
Source: lib/context.x:239
Context.export_nested
Var Context.export_nested(Context c, 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:219
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:93
Context.initialize
void Context.initialize(void)
Registers Context cleanup before workers can start.
Source: lib/context.x:358
Design notes
Context owns one bounded unit of runtime work: a Scope lifetime with its
Error and Match state and, when isolated, a nested canonical-value
pool. Export carries a value out before close reclaims the rest: it moves
built-in storage the source Scope owns and recanonicalizes immutable
values only when the source’s private pool owns them.
Tests and examples
make verify (unittest/test-context.x).