Struct wasmer::WasmPtr

#[repr(transparent)]
pub struct WasmPtr<T: Copy, Ty = Item> { /* fields omitted */ }

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(memory: Memory, ptr: WasmPtr<u32>) {
    let derefed_ptr = ptr.deref(&memory).expect("pointer in bounds");
    let inner_val: u32 = derefed_ptr.get();
    println!("Got {} from Wasm memory address 0x{:X}", inner_val, ptr.offset());
    // update the value being pointed to
    derefed_ptr.set(inner_val + 1);
}

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

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

fn update_vector_3(memory: Memory, ptr: WasmPtr<V3>) {
    let derefed_ptr = ptr.deref(&memory).expect("pointer in bounds");
    let mut inner_val: V3 = derefed_ptr.get();
    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.set(inner_val);
}

Implementations

impl<T: Copy, Ty> WasmPtr<T, Ty>

Methods relevant to all types of WasmPtr.

pub fn new(offset: u32) -> Self

Create a new WasmPtr at the given offset.

pub fn offset(self) -> u32

Get the offset into Wasm linear memory for this WasmPtr.

impl<T: Copy + ValueType> WasmPtr<T, Item>

Methods for WasmPtrs to data that can be dereferenced, namely to types that implement ValueType, meaning that they’re valid for all possible bit patterns.

pub fn deref<'a>(self, memory: &'a Memory) -> Option<&'a Cell<T>>

Dereference the WasmPtr getting access to a &Cell<T> allowing for reading and mutating of the inner value.

This method is unsound if used with unsynchronized shared memory. If you’re unsure what that means, it likely does not apply to you. This invariant will be enforced in the future.

pub unsafe fn deref_mut<'a>(self, memory: &'a Memory) -> Option<&'a mut Cell<T>>

Mutably dereference this WasmPtr getting a &mut Cell<T> allowing for direct access to a &mut T.

Safety

• This method does not do any aliasing checks: it’s possible to create &mut T that point to the same memory. You should ensure that you have exclusive access to Wasm linear memory before calling this method.

impl<T: Copy + ValueType> WasmPtr<T, Array>

Methods for WasmPtrs to arrays of data that can be dereferenced, namely to types that implement ValueType, meaning that they’re valid for all possible bit patterns.

pub fn deref(
    self,
    memory: &Memory,
    index: u32,
    length: u32
) -> Option<&[Cell<T>]>

Dereference the WasmPtr getting access to a &[Cell<T>] allowing for reading and mutating of the inner values.

This method is unsound if used with unsynchronized shared memory. If you’re unsure what that means, it likely does not apply to you. This invariant will be enforced in the future.

pub unsafe fn deref_mut(
    self,
    memory: &Memory,
    index: u32,
    length: u32
) -> Option<&mut [Cell<T>]>

Mutably dereference this WasmPtr getting a &mut [Cell<T>] allowing for direct access to a &mut [T].

Safety

• This method does not do any aliasing checks: it’s possible to create &mut T that point to the same memory. You should ensure that you have exclusive access to Wasm linear memory before calling this method.

pub unsafe fn get_utf8_str<'a>(
    self,
    memory: &'a Memory,
    str_len: u32
) -> Option<&'a str>

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

Note that . The underlying data can be mutated if the Wasm is allowed to execute or an aliasing WasmPtr is used to mutate memory.

Safety

This method returns a reference to Wasm linear memory. The underlying data can be mutated if the Wasm is allowed to execute or an aliasing WasmPtr is used to mutate memory.

str has invariants that must not be broken by mutating Wasm memory. Thus the caller must ensure that the backing memory is not modified while the reference is held.

Additionally, if memory is dynamic, the caller must also ensure that memory is not grown while the reference is held.

pub fn get_utf8_string(self, memory: &Memory, str_len: u32) -> Option<String>

Get a UTF-8 String from the WasmPtr with the given length.

an aliasing WasmPtr is used to mutate memory.

pub unsafe fn get_utf8_str_with_nul<'a>(
    self,
    memory: &'a Memory
) -> Option<&'a str>

Get a UTF-8 string from the WasmPtr, where the string is nul-terminated.

Note that this does not account for UTF-8 strings that contain nul themselves, WasmPtr::get_utf8_str has to be used for those.

Safety

This method behaves similarly to WasmPtr::get_utf8_str, all safety invariants on that method must also be upheld here.

pub fn get_utf8_string_with_nul(self, memory: &Memory) -> Option<String>

Get a UTF-8 String from the WasmPtr, where the string is nul-terminated.

Note that this does not account for UTF-8 strings that contain nul themselves, WasmPtr::get_utf8_string has to be used for those.

Trait Implementations

impl<T: Copy, Ty> Clone for WasmPtr<T, Ty>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Copy, Ty> Debug for WasmPtr<T, Ty>

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

Formats the value using the given formatter.

impl<T: Copy, Ty> FromToNativeWasmType for WasmPtr<T, Ty>

type Native = i32

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.

impl<T: Copy, Ty> PartialEq<WasmPtr<T, Ty>> for WasmPtr<T, Ty>

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 !=.

impl<T: Copy, Ty> Copy for WasmPtr<T, Ty>

impl<T: Copy, Ty> Eq for WasmPtr<T, Ty>

impl<T: Copy, Ty> ValueType for WasmPtr<T, Ty>