Struct UninitializedSandbox 

pub struct UninitializedSandbox { /* private fields */ }

A preliminary sandbox that represents allocated memory and registered host functions, but has not yet created the underlying virtual machine.

This struct holds the configuration and setup needed for a sandbox without actually creating the VM. It allows you to:

• Set up memory layout and load guest binary data
• Register host functions that will be available to the guest
• Configure sandbox settings before VM creation

The virtual machine is not created until you call evolve to transform this into an initialized MultiUseSandbox.

Implementations

impl UninitializedSandbox

pub fn new<'a, 'b>( env: impl Into<GuestEnvironment<'a, 'b>>, cfg: Option<SandboxConfiguration>, ) -> Result<Self>

Creates a new uninitialized sandbox for the given guest environment.

The guest binary can be provided as either a file path or memory buffer. An optional configuration can customize memory sizes and sandbox settings. After creation, register host functions using register before calling evolve to complete initialization and create the VM.

pub fn evolve(self) -> Result<MultiUseSandbox>

Creates and initializes the virtual machine, transforming this into a ready-to-use sandbox.

This method consumes the UninitializedSandbox and performs the final initialization steps to create the underlying virtual machine. Once evolved, the resulting MultiUseSandbox can execute guest code and handle function calls.

pub fn map_file_cow( &mut self, file_path: &Path, guest_base: u64, label: Option<&str>, ) -> Result<u64>

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

The file mapping is prepared immediately (host-side OS work) but the actual VM-side mapping is deferred until evolve().

An optional label identifies this mapping in the PEB’s FileMappingInfo array (max 63 bytes, defaults to the file name).

The guest_base must be page-aligned and must lie outside the sandbox’s primary shared memory region (BASE_ADDRESS to BASE_ADDRESS + shared_mem_size).

Returns the length of the mapping in bytes.

pub fn shared_mem_size(&self) -> usize

Returns the total size of the sandbox shared memory region in bytes.

This is useful for placing file mappings at guest physical addresses that don’t overlap the primary shared memory slot.

pub fn set_max_guest_log_level(&mut self, log_level: LevelFilter)

Sets the maximum log level for guest code execution.

If not set, the log level is determined by the RUST_LOG environment variable, defaulting to [LevelFilter::Error] if unset.

pub fn register<Args: ParameterTuple, Output: SupportedReturnType>( &mut self, name: impl AsRef<str>, host_func: impl Into<HostFunction<Output, Args>>, ) -> Result<()>

Registers a host function that the guest can call.

pub fn register_print( &mut self, print_func: impl Into<HostFunction<i32, (String,)>>, ) -> Result<()>

Registers the special “HostPrint” function for guest printing.

This overrides the default behavior of writing to stdout. The function expects the signature FnMut(String) -> i32 and will be called when the guest wants to print output.

Trait Implementations

impl Debug for UninitializedSandbox

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

Formats the value using the given formatter.

impl Registerable for UninitializedSandbox

fn register_host_function<Args: ParameterTuple, Output: SupportedReturnType>( &mut self, name: &str, hf: impl Into<HostFunction<Output, Args>>, ) -> Result<()>

Register a primitive host function