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. The sandbox supports creating snapshots and restoring to previous states.

Sandbox Poisoning

The sandbox becomes poisoned when the guest is not run to completion, leaving it in an inconsistent state that could compromise memory safety, data integrity, or security.

When Does Poisoning Occur?

Poisoning happens when guest execution is interrupted before normal completion:

• Guest panics or aborts - When a guest function panics, crashes, or calls abort(), the normal cleanup and unwinding process is interrupted
• Invalid memory access - Attempts to read/write/execute memory outside allowed regions
• Stack overflow - Guest exhausts its stack space during execution
• Heap exhaustion - Guest runs out of heap memory
• Host-initiated cancellation - Calling InterruptHandle::kill() to forcefully terminate an in-progress guest function

Why This Is Unsafe

When guest execution doesn’t complete normally, critical cleanup operations are skipped:

• Memory leaks - Heap allocations remain unreachable as the call stack is unwound
• Corrupted allocator state - Memory allocator metadata (free lists, heap headers) left inconsistent
• Locked resources - Mutexes or other synchronization primitives remain locked
• Partial state updates - Data structures left half-modified (corrupted linked lists, inconsistent hash tables, etc.)

Recovery

Use restore() with a snapshot taken before poisoning occurred. This is the only safe way to recover - it completely replaces all memory state, eliminating any inconsistencies. See restore() for details.

Implementations

impl MultiUseSandbox

pub fn snapshot(&mut self) -> Result<Snapshot>

Creates a snapshot of the sandbox’s current memory state.

The snapshot is tied to this specific sandbox instance and can only be restored to the same sandbox it was created from.

Poisoned Sandbox

This method will return crate::HyperlightError::PoisonedSandbox if the sandbox is currently poisoned. Snapshots can only be taken from non-poisoned sandboxes.

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Modify sandbox state
sandbox.call_guest_function_by_name::<i32>("SetValue", 42)?;

// Create snapshot belonging to this sandbox
let snapshot = sandbox.snapshot()?;

pub fn restore(&mut self, snapshot: &Snapshot) -> Result<()>

Restores the sandbox’s memory to a previously captured snapshot state.

The snapshot must have been created from this same sandbox instance. Attempting to restore a snapshot from a different sandbox will return a SnapshotSandboxMismatch error.

Poison State Recovery

This method automatically clears any poison state when successful. This is safe because:

• Snapshots can only be taken from non-poisoned sandboxes
• Restoration completely replaces all memory state, eliminating any inconsistencies caused by incomplete guest execution

What Gets Fixed During Restore

When a poisoned sandbox is restored, the memory state is completely reset:

• Leaked heap memory - All allocations from interrupted execution are discarded
• Corrupted allocator metadata - Free lists and heap headers restored to consistent state
• Locked mutexes - All lock state is reset
• Partial updates - Data structures restored to their pre-execution state

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Take initial snapshot from this sandbox
let snapshot = sandbox.snapshot()?;

// Modify sandbox state
sandbox.call_guest_function_by_name::<i32>("SetValue", 100)?;
let value: i32 = sandbox.call_guest_function_by_name("GetValue", ())?;
assert_eq!(value, 100);

// Restore to previous state (same sandbox)
sandbox.restore(&snapshot)?;
let restored_value: i32 = sandbox.call_guest_function_by_name("GetValue", ())?;
assert_eq!(restored_value, 0); // Back to initial state

Recovering from Poison

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Take snapshot before potentially poisoning operation
let snapshot = sandbox.snapshot()?;

// This might poison the sandbox (guest not run to completion)
let result = sandbox.call::<()>("guest_panic", ());
if result.is_err() {
    if sandbox.poisoned() {
        // Restore from snapshot to clear poison
        sandbox.restore(&snapshot)?;
        assert!(!sandbox.poisoned());
         
        // Sandbox is now usable again
        sandbox.call::<String>("Echo", "hello".to_string())?;
    }
}

pub fn call<Output: SupportedReturnType>( &mut self, func_name: &str, args: impl ParameterTuple, ) -> Result<Output>

Calls a guest function by name with the specified arguments.

Changes made to the sandbox during execution are persisted.

Poisoned Sandbox

This method will return crate::HyperlightError::PoisonedSandbox if the sandbox is already poisoned before the call. Use restore() to recover from a poisoned state.

Sandbox Poisoning

If this method returns an error, the sandbox may be poisoned if the guest was not run to completion (due to panic, abort, memory violation, stack/heap exhaustion, or forced termination). Use poisoned() to check the poison state and restore() to recover if needed.

If this method returns Ok, the sandbox is guaranteed to not be poisoned - the guest function completed successfully and the sandbox state is consistent.

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Call function with no arguments
let result: i32 = sandbox.call("GetCounter", ())?;

// Call function with single argument
let doubled: i32 = sandbox.call("Double", 21)?;
assert_eq!(doubled, 42);

// Call function with multiple arguments
let sum: i32 = sandbox.call("Add", (10, 32))?;
assert_eq!(sum, 42);

// Call function returning string
let message: String = sandbox.call("Echo", "Hello, World!".to_string())?;
assert_eq!(message, "Hello, World!");

Handling Potential Poisoning

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Take snapshot before risky operation
let snapshot = sandbox.snapshot()?;

// Call potentially unsafe guest function
let result = sandbox.call::<String>("RiskyOperation", "input".to_string());

// Check if the call failed and poisoned the sandbox
if let Err(e) = result {
    eprintln!("Guest function failed: {}", e);
     
    if sandbox.poisoned() {
        eprintln!("Sandbox was poisoned, restoring from snapshot");
        sandbox.restore(&snapshot)?;
    }
}

pub unsafe fn map_region(&mut self, rgn: &MemoryRegion) -> Result<()>

Maps a region of host memory into the sandbox address space.

The base address and length must meet platform alignment requirements (typically page-aligned). The region_type field is ignored as guest page table entries are not created.

Poisoned Sandbox

This method will return crate::HyperlightError::PoisonedSandbox if the sandbox is currently poisoned. Use restore() to recover from a poisoned state.

Safety

The caller must ensure the host memory region remains valid and unmodified for the lifetime of self.

pub fn map_file_cow(&mut self, _fp: &Path, _guest_base: u64) -> Result<u64>

Map the contents of a file into the guest at a particular address

Returns the length of the mapping in bytes.

Poisoned Sandbox

This method will return crate::HyperlightError::PoisonedSandbox if the sandbox is currently poisoned. Use restore() to recover from a poisoned state.

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

Returns a handle for interrupting guest execution.

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Get interrupt handle before starting long-running operation
let interrupt_handle = sandbox.interrupt_handle();

// Spawn thread to interrupt after timeout
let handle_clone = interrupt_handle.clone();
thread::spawn(move || {
    thread::sleep(Duration::from_secs(5));
    handle_clone.kill();
});

// This call may be interrupted by the spawned thread
let result = sandbox.call_guest_function_by_name::<i32>("LongRunningFunction", ());

pub fn poisoned(&self) -> bool

Returns whether the sandbox is currently poisoned.

A poisoned sandbox is in an inconsistent state due to the guest not running to completion. All operations will be rejected until the sandbox is restored from a non-poisoned snapshot.

Causes of Poisoning

The sandbox becomes poisoned when guest execution is interrupted:

• Panics/Aborts - Guest code panics or calls abort()
• Invalid Memory Access - Read/write/execute violations
• Stack Overflow - Guest exhausts stack space
• Heap Exhaustion - Guest runs out of heap memory
• Forced Termination - InterruptHandle::kill() called during execution

Recovery

To clear the poison state, use restore() with a snapshot that was taken before the sandbox became poisoned.

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None
)?.evolve()?;

// Check if sandbox is poisoned
if sandbox.poisoned() {
    println!("Sandbox is poisoned and needs attention");
}

Trait Implementations

impl Callable for MultiUseSandbox

fn call<Output: SupportedReturnType>( &mut self, func_name: &str, args: impl ParameterTuple, ) -> Result<Output>

Call a guest function dynamically

impl Debug for MultiUseSandbox

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

Formats the value using the given formatter.