Struct lucet_runtime::vmctx::Vmctx

pub struct Vmctx { /* fields omitted */ }

An opaque handle to a running instance's context.

Methods

impl Vmctx

pub unsafe fn from_raw(vmctx: *mut lucet_vmctx) -> Vmctx

Create a Vmctx from the compiler-inserted vmctx argument in a guest function.

This is almost certainly not what you want to use to get a Vmctx; instead use the first argument of a function with the #[lucet_hostcall] attribute, which must have the type &mut Vmctx.

pub fn as_raw(&self) -> *mut lucet_vmctx

Return the underlying vmctx pointer.

pub fn heap(&self) -> Ref<[u8]>

Return the WebAssembly heap as a slice of bytes.

If the heap is already mutably borrowed by heap_mut(), the instance will terminate with TerminationDetails::BorrowError.

pub fn heap_mut(&self) -> RefMut<[u8]>

Return the WebAssembly heap as a mutable slice of bytes.

If the heap is already borrowed by heap() or heap_mut(), the instance will terminate with TerminationDetails::BorrowError.

pub fn check_heap<T>(&self, ptr: *const T, len: usize) -> bool

Check whether a given range in the host address space overlaps with the memory that backs the instance heap.

pub fn contains_embed_ctx<T>(&self) -> bool where
    T: Any, 

Check whether a context value of a particular type exists.

pub fn get_embed_ctx<T>(&self) -> Ref<T> where
    T: Any, 

Get a reference to a context value of a particular type.

If a context of that type does not exist, the instance will terminate with TerminationDetails::CtxNotFound.

If the context is already mutably borrowed by get_embed_ctx_mut, the instance will terminate with TerminationDetails::BorrowError.

pub fn get_embed_ctx_mut<T>(&self) -> RefMut<T> where
    T: Any, 

Get a mutable reference to a context value of a particular type.

If a context of that type does not exist, the instance will terminate with TerminationDetails::CtxNotFound.

If the context is already borrowed by some other use of get_embed_ctx or get_embed_ctx_mut, the instance will terminate with TerminationDetails::BorrowError.

pub unsafe fn terminate_no_unwind(&mut self, details: TerminationDetails) -> !

Terminate this guest and return to the host context without unwinding.

This is almost certainly not what you want to use to terminate an instance from a hostcall, as any resources currently in scope will not be dropped. Instead, use lucet_hostcall_terminate! which unwinds to the enclosing hostcall body.

pub fn grow_memory(&mut self, additional_pages: u32) -> Result<u32, Error>

Grow the guest memory by the given number of WebAssembly pages.

On success, returns the number of pages that existed before the call.

pub fn globals(&self) -> Ref<[GlobalValue]>

Return the WebAssembly globals as a slice of i64s.

If the globals are already mutably borrowed by globals_mut(), the instance will terminate with TerminationDetails::BorrowError.

pub fn globals_mut(&self) -> RefMut<[GlobalValue]>

Return the WebAssembly globals as a mutable slice of i64s.

If the globals are already borrowed by globals() or globals_mut(), the instance will terminate with TerminationDetails::BorrowError.

pub fn get_func_from_idx(
    &self,
    table_idx: u32,
    func_idx: u32
) -> Result<FunctionHandle, Error>

Get a function pointer by WebAssembly table and function index.

This is useful when a hostcall takes a function pointer as its argument, as WebAssembly uses table indices as its runtime representation of function pointers.

Safety

We do not currently reflect function type information into the Rust type system, so callers of the returned function must take care to cast it to the correct type before calling. The correct type will include the vmctx argument, which the caller is responsible for passing from its own context.

There is currently no guarantee that guest functions will return before faulting, or terminating the instance in a subsequent hostcall. This means that any Rust resources that are held open when the guest function is called might be leaked if the guest function, for example, divides by zero. Work to make this safer is ongoing.

use lucet_runtime_macros::lucet_hostcall;
use lucet_runtime_internals::lucet_hostcall_terminate;
use lucet_runtime_internals::vmctx::{lucet_vmctx, Vmctx};

#[lucet_hostcall]
#[no_mangle]
pub unsafe extern "C" fn hostcall_call_binop(
    vmctx: &mut Vmctx,
    binop_table_idx: u32,
    binop_func_idx: u32,
    operand1: u32,
    operand2: u32,
) -> u32 {
    if let Ok(binop) = vmctx.get_func_from_idx(binop_table_idx, binop_func_idx) {
        let typed_binop = std::mem::transmute::<
            usize,
            extern "C" fn(*mut lucet_vmctx, u32, u32) -> u32,
        >(binop.ptr.as_usize());
        unsafe { (typed_binop)(vmctx.as_raw(), operand1, operand2) }
    } else {
        lucet_hostcall_terminate!("invalid function index")
    }
}

pub fn yield_(&mut self)

Suspend the instance, returning an empty RunResult::Yielded to where the instance was run or resumed.

After suspending, the instance may be resumed by the host using Instance::resume().

(The reason for the trailing underscore in the name is that Rust reserves yield as a keyword for future use.)

pub fn yield_expecting_val<R>(&mut self) -> R where
    R: 'static + Any, 

Suspend the instance, returning an empty RunResult::Yielded to where the instance was run or resumed.

After suspending, the instance may be resumed by calling Instance::resume_with_val() from the host with a value of type R.

pub fn yield_val<A>(&mut self, val: A) where
    A: 'static + Any, 

Suspend the instance, returning a value in RunResult::Yielded to where the instance was run or resumed.

After suspending, the instance may be resumed by the host using Instance::resume().

pub fn yield_val_expecting_val<A, R>(&mut self, val: A) -> R where
    A: 'static + Any,
    R: 'static + Any, 

Suspend the instance, returning a value in RunResult::Yielded to where the instance was run or resumed.

After suspending, the instance may be resumed by calling Instance::resume_with_val() from the host with a value of type R.

Trait Implementations

impl Debug for Vmctx

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

Formats the value using the given formatter.

impl Drop for Vmctx

fn drop(&mut self)

Executes the destructor for this type.

impl VmctxInternal for Vmctx

fn instance(&self) -> &Instance

Get a reference to the Instance for this guest.

unsafe fn instance_mut(&self) -> &mut Instance

Get a mutable reference to the Instance for this guest.

fn try_take_resumed_val<R>(&self) -> Option<R> where
    R: 'static + Any, 

Try to take and return the value passed to Instance::resume_with_val().

fn yield_val_try_val<A, R>(&mut self, val: A) -> Option<R> where
    A: 'static + Any,
    R: 'static + Any, 

Suspend the instance, returning a value in RunResult::Yielded to where the instance was run or resumed.