Struct MultiUseSandbox 

pub struct MultiUseSandbox { /* private fields */ }

A fully initialized sandbox that can execute guest functions multiple times.

Guest functions can be called repeatedly while maintaining state between calls.

Post-Stage-F: the upstream snapshot() / restore() / map_file_cow() rollback machinery is gone along with the CoW PT marking that backed it. If a guest call fails for any reason, drop the sandbox and build a new one — that’s the only recovery path now (and the one nub already used).

Implementations

impl MultiUseSandbox

pub fn id(&self) -> u64

Returns this sandbox’s unique id.

pub fn vcpu_count(&self) -> Result<usize>

Fixed vCPU pool size configured for this sandbox.

pub fn call_raw(&self, fn_id: u32, payload: &[u8]) -> Result<Vec<u8>>

Call a guest function by fn_id with a raw byte payload. Returns the response payload bytes on success.

Wire format: the host serialises a [nub_host_common::rpc::Request] (rkyv) carrying fn_id and payload, ships it via the input data ring, the guest decodes

• dispatches + writes a Response to the output ring, and we read + check status before returning the inner payload.

Changes made to the sandbox during execution are persisted. On failure the sandbox should be dropped and rebuilt.

pub fn call_raw_on_vcpu( &self, vcpu_index: usize, fn_id: u32, payload: &[u8], ) -> Result<Vec<u8>>

Serialized control-plane call on a selected vCPU lane. This still uses the legacy shared input/output rings and therefore must not be used as the concurrent invoke mechanism; it exists to validate and bootstrap non-primary lanes. Concurrent invokes use the per-lane worker slots.

pub fn invoke_cached_parallel( &self, job_id: u64, packet: &InvokePacket, ) -> Result<InvocationResult>

Submit an invoke packet through the per-lane parallel worker slots.

Workers are started lazily and remain hot for subsequent invoke calls. The legacy raw RPC channel remains the serialized control plane. User job waits deliberately have no host-side timeout; without a cancellation API, the lane must stay reserved until the guest reports completion or the worker exits.

pub fn evict_jit_all_parallel(&self) -> Result<()>

Bench-only: evict guest JIT caches while keeping the hot invoke worker pool alive. The legacy raw RPC path stops workers before entering the shared control ring; cold benchmarks call this every iteration, so using the worker slot protocol avoids measuring worker teardown/startup.

All lanes are reserved first. That preserves the eviction invariant: no frame runtime can be live while image arenas and templates are dropped.

pub fn put_cap(&self, cap: &Cap) -> Result<AbiCapHash>

Publish a [Cap] into the guest’s heap-resident cap directory via the [FN_ID_NUB_PUT_CAP] RPC.

rkyv-encodes cap directly via [rkyv::to_bytes]; the resulting bytes are shipped via Self::call_raw and the guest-computed CapHash is read back. On the guest side, the cap is inserted into the nub_arch_x86::state_cache::DIRECTORY map, keyed by hash.

Caps whose graph still holds a CapHashOrRef::Ref target (cache-local lifetime handles with no resolution on the receive side) fail at rkyv-encode with a typed CapHasRefError wrapped in the rancor error chain. Other encode/decode failures are surfaced as HyperlightError::Error. A sentinel response (all-0xFF hash) from the guest is also turned into an error.

pub fn put_cap_with_hash(&self, hash: AbiCapHash, cap: &Cap) -> Result<()>

Pre-hashed put: idempotent fast path that short-circuits the full Self::put_cap RPC when this sandbox has already published hash.

Behaviour:

• If hash is in the host-side published_blobs set, return immediately — we already shipped this cap and the blobs tier never evicts, so the guest still holds it. We skip the rkyv encode + VMEXIT + guest decode + merkle walk + directory insert. This is the hot path for bench loops that re-publish the same cap graph every iteration.
• Otherwise, ship put_cap(cap), debug-assert the returned hash matches hash, and record it.

We deliberately do not check the guest’s directory directly: the guest’s CacheDirectory is a hashbrown table built with a different SIMD Group width than the host’s hashbrown (see published_blobs), so a host-side deref of it is unsound.

pub fn interrupt_handle(&self) -> Arc<dyn InterruptHandle>

Returns a handle for interrupting guest execution.

Trait Implementations

impl Debug for MultiUseSandbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Registerable for MultiUseSandbox

Allow registering host functions on an already-evolved crate::MultiUseSandbox.

The primary entry point for host-function registration is the UninitializedSandbox impl above — that’s the lifecycle phase where the guest hasn’t yet been allowed to issue host calls. There are, however, cases where a MultiUseSandbox is obtained without traversing the Uninitialized → evolve() path:

• Sandboxes loaded from a persisted snapshot.
• Any future API that yields a MultiUseSandbox directly.

In those cases the caller never had a chance to call register_host_function on an UninitializedSandbox, so we expose the same trait implementation here for late registration. The guest’s dispatcher resolves by fn_id at call time, so inserting into the registry after evolve() is semantically safe as long as the first host-function invocation happens after registration completes.

fn register_host_function(&mut self, fn_id: u32, func: HostFn) -> Result<()>

Register func to be invoked by the guest under the given fn_id. Overwrites any prior entry for that id.