Struct WasmPtr

#[repr(transparent)]
pub(crate) struct WasmPtr<T, M = Memory32>
where
    M: MemorySize,
{
    offset: <M as MemorySize>::Offset,
    _phantom: PhantomData<T>,
}

A zero-cost type that represents a pointer to something in Wasm linear memory.

This type can be used directly in the host function arguments:

pub fn host_import(mut env: FunctionEnvMut<()>, memory: Memory, ptr: WasmPtr<u32>) {
    let memory = memory.view(&env);
    let derefed_ptr = ptr.deref(&memory);
    let inner_val: u32 = derefed_ptr.read().expect("pointer in bounds");
    println!("Got {} from Wasm memory address 0x{:X}", inner_val, ptr.offset());
    // update the value being pointed to
    derefed_ptr.write(inner_val + 1).expect("pointer in bounds");
}

This type can also be used with primitive-filled structs, but be careful of guarantees required by ValueType.

// This is safe as the 12 bytes represented by this struct
// are valid for all bit combinations.
#[derive(Copy, Clone, Debug, ValueType)]
#[repr(C)]
struct V3 {
    x: f32,
    y: f32,
    z: f32
}

fn update_vector_3(mut env: FunctionEnvMut<()>, memory: Memory, ptr: WasmPtr<V3>) {
    let memory = memory.view(&env);
    let derefed_ptr = ptr.deref(&memory);
    let mut inner_val: V3 = derefed_ptr.read().expect("pointer in bounds");
    println!("Got {:?} from Wasm memory address 0x{:X}", inner_val, ptr.offset());
    // update the value being pointed to
    inner_val.x = 10.4;
    derefed_ptr.write(inner_val).expect("pointer in bounds");
}

Fields

offset: <M as MemorySize>::Offset

_phantom: PhantomData<T>

Implementations

impl<T, M> WasmPtr<T, M>

where M: MemorySize,

pub fn new(offset: <M as MemorySize>::Offset) -> WasmPtr<T, M>

Create a new WasmPtr at the given offset.

pub fn offset(&self) -> <M as MemorySize>::Offset

Get the offset into Wasm linear memory for this WasmPtr.

pub fn cast<U>(self) -> WasmPtr<U, M>

Casts this WasmPtr to a WasmPtr of a different type.

pub fn null() -> WasmPtr<T, M>

Returns a null UserPtr.

pub fn is_null(&self) -> bool

Checks whether the WasmPtr is null.

pub fn add_offset( self, offset: <M as MemorySize>::Offset, ) -> Result<WasmPtr<T, M>, MemoryAccessError>

Calculates an offset from the current pointer address. The argument is in units of T.

This method returns an error if an address overflow occurs.

pub fn sub_offset( self, offset: <M as MemorySize>::Offset, ) -> Result<WasmPtr<T, M>, MemoryAccessError>

Calculates an offset from the current pointer address. The argument is in units of T.

This method returns an error if an address underflow occurs.

impl<T, M> WasmPtr<T, M>

where T: ValueType, M: MemorySize,

pub fn deref<'a>(&self, view: &'a MemoryView<'_>) -> WasmRef<'a, T>

Creates a WasmRef from this WasmPtr which allows reading and mutating of the value being pointed to.

pub fn read(&self, view: &MemoryView<'_>) -> Result<T, MemoryAccessError>

Reads the address pointed to by this WasmPtr in a memory.

pub fn write( &self, view: &MemoryView<'_>, val: T, ) -> Result<(), MemoryAccessError>

Writes to the address pointed to by this WasmPtr in a memory.

pub fn slice<'a>( &self, view: &'a MemoryView<'_>, len: <M as MemorySize>::Offset, ) -> Result<WasmSlice<'a, T>, MemoryAccessError>

Creates a WasmSlice starting at this WasmPtr which allows reading and mutating of an array of value being pointed to.

Returns a MemoryAccessError if the slice length overflows a 64-bit address.

pub fn read_until( &self, view: &MemoryView<'_>, end: impl FnMut(&T) -> bool, ) -> Result<Vec<T>, MemoryAccessError>

Reads a sequence of values from this WasmPtr until a value that matches the given condition is found.

This last value is not included in the returned vector.

pub fn access<'a>( &self, view: &'a MemoryView<'_>, ) -> Result<WasmRefAccess<'a, T>, MemoryAccessError>

Creates a WasmAccess

impl<M> WasmPtr<u8, M>

where M: MemorySize,

pub fn read_utf8_string( &self, view: &MemoryView<'_>, len: <M as MemorySize>::Offset, ) -> Result<String, MemoryAccessError>

Reads a UTF-8 string from the WasmPtr with the given length.

This method is safe to call even if the memory is being concurrently modified.

pub fn read_utf8_string_with_nul( &self, view: &MemoryView<'_>, ) -> Result<String, MemoryAccessError>

Reads a null-terminated UTF-8 string from the WasmPtr.

This method is safe to call even if the memory is being concurrently modified.

Trait Implementations

impl<T, M> Clone for WasmPtr<T, M>

where T: ValueType, M: MemorySize,

fn clone(&self) -> WasmPtr<T, M>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, M> Debug for WasmPtr<T, M>

where T: ValueType, M: MemorySize,

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

Formats the value using the given formatter.

impl<T, M> FromToNativeWasmType for WasmPtr<T, M>

where T: ValueType, M: MemorySize, <M as MemorySize>::Native: NativeWasmTypeInto,

type Native = <M as MemorySize>::Native

Native Wasm type.

fn to_native(self) -> <WasmPtr<T, M> as FromToNativeWasmType>::Native

Convert self to Self::Native.

fn from_native( n: <WasmPtr<T, M> as FromToNativeWasmType>::Native, ) -> WasmPtr<T, M>

Convert a value of kind Self::Native to Self.

fn is_from_store(&self, _store: &impl AsStoreRef) -> bool

Returns whether the given value is from the given store.

impl<T, M> PartialEq for WasmPtr<T, M>

where T: ValueType, M: MemorySize,

fn eq(&self, other: &WasmPtr<T, M>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, M> ValueType for WasmPtr<T, M>

where T: ValueType, M: MemorySize,

fn zero_padding_bytes(&self, _bytes: &mut [MaybeUninit<u8>])

This method is passed a byte slice which contains the byte representation of self. It must zero out any bytes which are uninitialized (e.g. padding bytes).

impl<T, M> Copy for WasmPtr<T, M>

where T: ValueType, M: MemorySize,

impl<T, M> Eq for WasmPtr<T, M>

where T: ValueType, M: MemorySize,