Struct AsyncBuiltinCtx 

pub struct AsyncBuiltinCtx { /* private fields */ }

Explicit handle to the parent VM’s execution context for the duration of one async-builtin call. Threaded into every async builtin by the dispatch loop (and the #[harn_builtin] macro), so context can no longer be “lost across a spawn boundary”: a handler that needs VM access receives or clones this handle deliberately instead of reading ambient state.

Holds the “template” child VM that closure-invoking host helpers clone via AsyncBuiltinCtx::child_vm, and whose output buffer collects text forwarded from VM-side closures via AsyncBuiltinCtx::forward_output. The dispatch loop drains that buffer back to the original parent VM after the async builtin returns. Cheap to clone: it is an Arc handle and everything heavy inside the Vm is shared.

Implementations

impl AsyncBuiltinCtx

pub fn from_vm(vm: Vm) -> Self

Construct a context around vm for host adapters that are not themselves async builtins but need to run VM-side closures.

pub fn child_vm(&self) -> Vm

Clone a fresh child VM from this context. The returned Vm shares the parent’s heavy state, so each closure-invoking handler gets its own cheap execution context.

Uses the inline clone: this child runs while the original parent is parked awaiting the builtin, so it inherits the parent’s held-lock keys for cross-context self-deadlock detection (HARN-ORC-011). Long-lived / detached contexts use AsyncBuiltinCtx::child_ctx instead, which does not inherit, since the parent keeps running there.

pub fn child_ctx(&self) -> Self

Create an independent context rooted at a fresh child VM. Long-lived local tasks use this instead of sharing the parent builtin’s output buffer after the parent future has returned.

This is a detached context: the new task runs independently of the original parent, so it must NOT inherit the parent’s held-lock keys (blocking on a parent-held lock is legitimately resolvable here). Uses the plain, non-inheriting child_vm() rather than Self::child_vm.

pub fn forward_output(&self, text: &str)

Forward captured output from a transient child VM (typically created via AsyncBuiltinCtx::child_vm and used to invoke a closure) back into this context’s output buffer. The dispatch loop drains that buffer back to the original parent VM after the async builtin returns.

Without this hook, log()/__io_print() calls inside post_turn_callback closures, tool handlers, and other VM-side closures invoked from async builtins would silently disappear because the transient child VM’s output buffer is dropped on scope exit.

Trait Implementations

impl Clone for AsyncBuiltinCtx

fn clone(&self) -> AsyncBuiltinCtx

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.