Enum GuestMemory

pub enum GuestMemory<'a> {
    Unshared(&'a mut [u8]),
    Shared(&'a [UnsafeCell<u8>]),
}

Representation of guest memory for wiggle-generated trait methods.

Guest memory is represented as an array of bytes. Memories are either “unshared” or “shared”. Unshared means that the host has exclusive access to the entire array of memory. This allows safe borrows into wasm linear memory. Shared memories can be modified at any time and are represented as an array of UnsafeCell<u8>.

This is generated by the wiggle bindings macros.

Variants

Unshared(&'a mut [u8])

Shared(&'a [UnsafeCell<u8>])

Implementations

impl<'a> GuestMemory<'a>

pub fn read<T>(&self, ptr: GuestPtr<T>) -> Result<T, GuestError>

where T: GuestType,

Read a value from the provided pointer.

This method will delegate to T’s implementation of read which will read a value from the ptr provided.

Errors

An error is returned if ptr is out of bounds, misaligned, or otherwise not valid to read from.

pub fn write<T>(&mut self, ptr: GuestPtr<T>, val: T) -> Result<(), GuestError>

where T: GuestType,

Writes the val provided to the ptr provided.

This commit will write a val into a guest’s linear memory. This will delegate to T’s implementation of write.

Errors

An error is returned if ptr is out of bounds, misaligned, or otherwise not valid to read from.

pub fn as_cow(&self, ptr: GuestPtr<[u8]>) -> Result<Cow<'_, [u8]>, GuestError>

Acquires a slice or owned copy of the memory pointed to by ptr.

This method will attempt to borrow ptr directly from linear memory. If memory is shared and cannot be borrowed directly then an owned copy is returned instead.

Errors

An error is returned if ptr is out of bounds, misaligned, or otherwise not valid to read from.

pub fn as_cow_str(&self, ptr: GuestPtr<str>) -> Result<Cow<'_, str>, GuestError>

Same as GuestMemory::as_cow but for strings.

Errors

An error is returned if ptr is out of bounds, misaligned, or otherwise not valid to read from.

pub fn as_slice(&self, ptr: GuestPtr<[u8]>) -> Result<Option<&[u8]>, GuestError>

Attempts to borrow a raw guest slice of memory pointed to by ptr.

This method will attempt to return a raw pointer into guest memory. This can only be done for Unshared memories. A Shared memory will return Ok(None) here.

Errors

An error is returned if ptr is out of bounds, misaligned, or otherwise not valid to read from.

pub fn as_str(&self, ptr: GuestPtr<str>) -> Result<Option<&str>, GuestError>

Same as GuestMemory::as_slice but for strings.

pub fn as_slice_mut( &mut self, ptr: GuestPtr<[u8]>, ) -> Result<Option<&mut [u8]>, GuestError>

Attempts return ptr as a raw slice of mutable bytes in wasm linear memory.

Like GuestMemory::as_slice this only works for Unshared memories and will not work for Shared memories.

pub fn to_vec<T>(&self, ptr: GuestPtr<[T]>) -> Result<Vec<T>, GuestError>

where T: GuestTypeTransparent + Copy,

Copies the data in the guest region into a Vec.

This is useful when one cannot use GuestMemory::as_slice, e.g., when pointing to a region of WebAssembly shared memory.

pub fn copy_from_slice<T>( &mut self, slice: &[T], ptr: GuestPtr<[T]>, ) -> Result<(), GuestError>

where T: GuestTypeTransparent + Copy,

Copies the data pointed to by slice into this guest region.

This method is a safe method to copy data from the host to the guest. This requires that self and slice have the same length. The pointee type T requires the GuestTypeTransparent trait which is an assertion that the representation on the host and on the guest is the same.

Errors

Returns an error if this guest pointer is out of bounds or if the length of this guest pointer is not equal to the length of the slice provided.

pub fn is_shared_memory(&self) -> bool

Returns whether this is a shared memory or not.

Trait Implementations

impl Send for GuestMemory<'_>

impl Sync for GuestMemory<'_>