Struct lucet_runtime_internals::context::ContextHandle

#[repr(C)]
pub struct ContextHandle { /* fields omitted */ }

A wrapper around a Context, primarily meant for use in test code.

Users of this library interact with contexts implicitly via Instance values, but for testing the context code independently, it is helpful to use contexts directly.

Movement of ContextHandle

ContextHandle keeps a pointer to a Context rather than keeping all of the data directly as fields in order to have better control over where that data lives in memory. We always want that data to be heap-allocated, and to never move once it has been initialized. The ContextHandle, by contrast, should be treated like a normal Rust value with no such restrictions.

Until the Unpin marker trait arrives in stable Rust, it is difficult to enforce this with the type system alone, so we use a bit of unsafety and (hopefully) clever API design to ensure that the data cannot be moved.

We create the Context within a box to allocate it on the heap, then convert it into a raw pointer to relinquish ownership. When accessing the internal structure via the DerefMut trait, data must not be moved out of the Context with functions like mem::replace.

Layout

Foreign code accesses the internal pointer in tests, so it is important that it is the first member, and that the struct is repr(C).

Methods

impl ContextHandle

pub fn new() -> Self

Create an all-zeroed ContextHandle.

pub fn create_and_init(
    stack: &mut [u64],
    fptr: usize,
    args: &[Val]
) -> Result<ContextHandle, Error>

Methods from Deref<Target = Context>

pub fn clear_retvals(&mut self)

Clear (zero) return values.

pub fn get_retval_gp(&self, idx: usize) -> u64

Get the general-purpose return value at index idx.

If this method is called before the context has returned from its original entrypoint, the result will be 0.

pub fn get_retval_fp(&self) -> __m128

Get the floating point return value.

If this method is called before the context has returned from its original entrypoint, the result will be 0.0.

pub fn get_untyped_retval(&self) -> UntypedRetVal

Get the return value as an UntypedRetVal.

This combines the 0th general-purpose return value, and the single floating-point return value.

Trait Implementations

impl Deref for ContextHandle

type Target = Context

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for ContextHandle

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for ContextHandle

fn drop(&mut self)

Executes the destructor for this type.