Struct SingleUseSandbox

pub struct SingleUseSandbox { /* private fields */ }

A sandbox implementation that supports calling no more than 1 guest function

Implementations

impl SingleUseSandbox

pub fn new_call_context(self) -> SingleUseGuestCallContext

Create a new SingleUseCallContext . The main purpose of the a SingleUseSandbox is to allow mutiple calls to guest functions from within a callback function.

Since this function consumes self, the returned SingleUseGuestCallContext is guaranteed mutual exclusion for calling functions within the sandbox.

Since this is a SingleUseSandbox, the returned context cannot be converted back into the original SingleUseSandbox. When it’s dropped, all the resources of the context and sandbox are released at once.

Example usage (compiled as a “no_run” doctest since the test binary will not be found):

use hyperlight_host::sandbox::{UninitializedSandbox, SingleUseSandbox};
use hyperlight_common::flatbuffer_wrappers::function_types::{ReturnType, ParameterValue, ReturnValue};
use hyperlight_host::sandbox_state::sandbox::EvolvableSandbox;
use hyperlight_host::sandbox_state::transition::Noop;
use hyperlight_host::GuestBinary;

// First, create a new uninitialized sandbox, then evolve it to become
// an initialized, single-use one.
let u_sbox = UninitializedSandbox::new(
    GuestBinary::FilePath("some_guest_binary".to_string()),
    None,
    None,
    None,
).unwrap();
let sbox: SingleUseSandbox = u_sbox.evolve(Noop::default()).unwrap();
// Next, create a new call context from the single-use sandbox.
// After this line, your code will not compile if you try to use the
// original `sbox` variable.
let mut ctx = sbox.new_call_context();


// Create a closure to call multiple guest functions usings the contexts
// call_from-func method. Assues that the loaded binary
// ("some_guest_binary") has a function therein called "SomeGuestFunc" and another called "SomeOtherGuestFunc"
// that take a single integer argument and return an integer.


let result = ctx.call_from_func( |call_ctx| {

match call_ctx.call(
    "SomeGuestFunc",
    ReturnType::Int,
    Some(vec![ParameterValue::Int(1)])
) {
    Ok(ReturnValue::Int(i)) => println!(
        "got successful return value {}",
        i,
    ),
    other => panic!(
        "failed to get return value as expected ({:?})",
        other,
    ),
}

match call_ctx.call(
    "SomeOtherGuestFunc",
    ReturnType::Int,
    Some(vec![ParameterValue::Int(1)])
) {
    Ok(ReturnValue::Int(i)) => println!(
        "got successful return value {}",
        i,
    ),
    other => panic!(
        "failed to get return value as expected ({:?})",
        other,
    ),
}

Ok(ReturnValue::Int(0))

});

// After the call context is dropped, the sandbox is also dropped.

pub fn call_guest_function_by_name( self, name: &str, ret: ReturnType, args: Option<Vec<ParameterValue>>, ) -> Result<ReturnValue>

Convenience for the following:

self.new_call_context().call(name, ret, args)

Trait Implementations

impl Debug for SingleUseSandbox

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

Formats the value using the given formatter.

impl Drop for SingleUseSandbox

fn drop(&mut self)

Executes the destructor for this type.

impl EvolvableSandbox<UninitializedSandbox, SingleUseSandbox, Noop<UninitializedSandbox, SingleUseSandbox>> for UninitializedSandbox

fn evolve( self, _: Noop<UninitializedSandbox, SingleUseSandbox>, ) -> Result<SingleUseSandbox>

Evolve self to a SingleUseSandbox without any additional metadata.

impl Sandbox for SingleUseSandbox

fn check_stack_guard(&self) -> Result<bool>

Check to ensure the current stack cookie matches the one that was selected when the stack was constructed.