Struct wasmer::WasmPtr

source · [−]

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

Expand description

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

source

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

Methods relevant to all types of WasmPtr.

source

pub fn new(offset: u32) -> Self

Create a new WasmPtr at the given offset.

source

pub fn offset(self) -> u32

Get the offset into Wasm linear memory for this WasmPtr.

source

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.

source

pub fn deref<'a>(self, memory: &'a Memory) -> Option<WasmCell<'a, 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.

source

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.

source

pub fn deref<'a>(
 self,
 memory: &'a Memory,
 index: u32,
 length: u32
) -> Option<Vec<WasmCell<'a, 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.

source

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.

source