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.

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.

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.

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

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.

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!");

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.

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.

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", ());

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.