pub struct LoadedWasmSandbox { /* private fields */ }Expand description
A sandbox that has both a Wasm engine and an arbitrary Wasm module loaded into memory.
LoadedWasmSandboxes are ready to execute
guest code and can execute a guest call, with call_guest_function,
multiple times. Each call to call_guest_function executes in the same
memory context. If you want to “reset” the memory context, create
a new LoadedWasmSandbox – either from another WasmSandbox or by
calling my_loaded_wasm_sandbox.devolve()?.evolve()?
Implementations§
Source§impl LoadedWasmSandbox
impl LoadedWasmSandbox
Sourcepub fn call_guest_function<Output: SupportedReturnType>(
&mut self,
fn_name: &str,
params: impl ParameterTuple,
) -> Result<Output>
pub fn call_guest_function<Output: SupportedReturnType>( &mut self, fn_name: &str, params: impl ParameterTuple, ) -> Result<Output>
Call the function in the guest with the name fn_name, passing
parameters params.
On success, return an Ok with the return
value and a new copy of Self suitable for further use. On failure,
return an appropriate Err.
§Errors
Returns Err(HyperlightError::PoisonedSandbox) if the sandbox is in a
poisoned state. Use restore() to recover a poisoned
sandbox before calling this method again.
Note: A sandbox becomes poisoned when a previous call fails due to
abnormal guest execution. That call returns the original error (e.g.,
ExecutionCanceledByHost from interrupt_handle().kill(), or errors
from guest panics, memory violations, etc.), and the sandbox is marked
as poisoned. This method then returns PoisonedSandbox on subsequent
calls until the sandbox is recovered.
Sourcepub fn snapshot(&mut self) -> Result<Arc<Snapshot>>
pub fn snapshot(&mut self) -> Result<Arc<Snapshot>>
Take a snapshot of the current state of the sandbox.
The snapshot can later be used with restore() to
return the sandbox to this state.
§Errors
Returns Err(HyperlightError::PoisonedSandbox) if the sandbox is in a
poisoned state. Use restore() with a previously
taken snapshot to recover before taking a new snapshot.
Sourcepub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()>
pub fn restore(&mut self, snapshot: Arc<Snapshot>) -> Result<()>
Restore the state of the sandbox to the state captured in the given snapshot.
This method clears the poisoned state if the sandbox was poisoned, making it usable again for guest function calls.
§Recovery from poisoned state
If a sandbox becomes poisoned (e.g., after interrupt_handle().kill()),
calling restore() with a valid snapshot will:
- Clear the poisoned state
- Reset memory to the snapshot state
- Allow subsequent
call_guest_function()calls to succeed
Sourcepub fn unload_module(self) -> Result<WasmSandbox>
pub fn unload_module(self) -> Result<WasmSandbox>
Unload the wasm module and return a WasmSandbox that can be
used to load another module.
This method defers calling restore() to
reset the sandbox to its pre-module state until a new module
is loaded. However, the sandbox will always be restored when a
new module is loaded, so a poisoned sandbox can be recovered
by unloading and reloading a module.
Sourcepub fn interrupt_handle(&self) -> Result<Arc<dyn InterruptHandle>>
pub fn interrupt_handle(&self) -> Result<Arc<dyn InterruptHandle>>
Get a handle to the interrupt handler for this sandbox, capable of interrupting guest execution.
Sourcepub fn status(&self) -> Result<SandboxStatus>
pub fn status(&self) -> Result<SandboxStatus>
Get the current lifecycle state of the sandbox.
§Errors
Returns an error if the sandbox is in an invalid state.
Sourcepub fn is_poisoned(&self) -> Result<bool>
👎Deprecated since 0.15.0: use status().is_poisoned() instead
pub fn is_poisoned(&self) -> Result<bool>
use status().is_poisoned() instead
Check if the sandbox is in a poisoned state.
A sandbox becomes poisoned when guest execution does not complete normally, such as after:
- Forced termination via
interrupt_handle().kill() - Guest panic or abort
- Memory violation
- Stack or heap exhaustion
Note: The call that causes poisoning returns the original error (e.g.,
ExecutionCanceledByHost), not PoisonedSandbox. The sandbox is marked
as poisoned after that error, and subsequent calls to
call_guest_function() will return
Err(HyperlightError::PoisonedSandbox).
A poisoned sandbox cannot execute guest functions until recovered via
restore(). Calling unload_module()
will also recover a poisoned sandbox since it performs a restore internally.
§Returns
Ok(true)if the sandbox is poisoned and needs recoveryOk(false)if the sandbox is healthy and can execute guest functionsErrif the sandbox is in an invalid state