Struct wasmer::WasmPtr

#[repr(transparent)]
pub struct WasmPtr<T, M: MemorySize = Memory32> { /* private fields */ }

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");
}

Implementations

impl<T, M: MemorySize> WasmPtr<T, M>

pub fn new(offset: M::Offset) -> Self

Create a new WasmPtr at the given offset.

pub fn offset(&self) -> M::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() -> Self

Returns a null UserPtr.

pub fn is_null(self) -> bool

Checks whether the WasmPtr is null.

pub fn add_offset(self, offset: M::Offset) -> Result<Self, 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::Offset) -> Result<Self, 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: ValueType, M: MemorySize> WasmPtr<T, M>

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::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.

impl<M: MemorySize> WasmPtr<u8, M>

pub fn read_utf8_string(
    self,
    view: &MemoryView<'_>,
    len: M::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: ValueType, M: MemorySize> Clone for WasmPtr<T, M>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: ValueType, M: MemorySize> Debug for WasmPtr<T, M>

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

Formats the value using the given formatter.

impl<T: ValueType, M: MemorySize> FromToNativeWasmType for WasmPtr<T, M>where
    <M as MemorySize>::Native: NativeWasmTypeInto,

type Native = <M as MemorySize>::Native

Native Wasm type.

fn to_native(self) -> Self::Native

Convert self to Self::Native.

fn from_native(n: Self::Native) -> Self

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: ValueType, M: MemorySize> PartialEq<WasmPtr<T, M>> for WasmPtr<T, M>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

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

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: ValueType, M: MemorySize> Copy for WasmPtr<T, M>

impl<T: ValueType, M: MemorySize> Eq for WasmPtr<T, M>