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 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.

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 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_with_extra_allowed_syscalls<Args: ParameterTuple, Output: SupportedReturnType>( &mut self, name: impl AsRef<str>, host_func: impl Into<HostFunction<Output, Args>>, extra_allowed_syscalls: impl IntoIterator<Item = ExtraAllowedSyscall>, ) -> Result<()>

Registers a host function with additional allowed syscalls during execution.

Unlike register, this variant allows specifying extra syscalls that will be permitted when the function handler runs.

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.

pub fn register_print_with_extra_allowed_syscalls( &mut self, print_func: impl Into<HostFunction<i32, (String,)>>, extra_allowed_syscalls: impl IntoIterator<Item = ExtraAllowedSyscall>, ) -> Result<()>

Registers the “HostPrint” function with additional allowed syscalls.

Like register_print, but allows specifying extra syscalls that will be permitted during function execution.

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

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

Register a primitive host function whose worker thread has extra permissive seccomp filters installed