Struct wasmer::Memory

pub struct Memory { /* private fields */ }

A WebAssembly memory instance.

A memory instance is the runtime representation of a linear memory. It consists of a vector of bytes and an optional maximum size.

The length of the vector always is a multiple of the WebAssembly page size, which is defined to be the constant 65536 – abbreviated 64Ki. Like in a memory type, the maximum size in a memory instance is given in units of this page size.

A memory created by the host or in WebAssembly code will be accessible and mutable from both host and WebAssembly.

Spec: https://webassembly.github.io/spec/core/exec/runtime.html#memory-instances

Implementations

impl Memory

pub fn new(store: &Store, ty: MemoryType) -> Result<Self, MemoryError>

Creates a new host Memory from the provided MemoryType.

This function will construct the Memory using the store BaseTunables.

Example

let m = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();

pub fn ty(&self) -> MemoryType

Returns the MemoryType of the Memory.

Example

let mt = MemoryType::new(1, None, false);
let m = Memory::new(&store, mt).unwrap();

assert_eq!(m.ty(), mt);

pub fn store(&self) -> &Store

Returns the Store where the Memory belongs.

Example

let m = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();

assert_eq!(m.store(), &store);

pub unsafe fn data_unchecked(&self) -> &[u8]

Retrieve a slice of the memory contents.

Safety

Until the returned slice is dropped, it is undefined behaviour to modify the memory contents in any way including by calling a wasm function that writes to the memory or by resizing the memory.

pub unsafe fn data_unchecked_mut(&self) -> &mut [u8]

Retrieve a mutable slice of the memory contents.

Safety

This method provides interior mutability without an UnsafeCell. Until the returned value is dropped, it is undefined behaviour to read or write to the pointed-to memory in any way except through this slice, including by calling a wasm function that reads the memory contents or by resizing this Memory.

pub fn data_ptr(&self) -> *mut u8

Returns the pointer to the raw bytes of the Memory.

pub fn data_size(&self) -> u64

Returns the size (in bytes) of the Memory.

pub fn size(&self) -> Pages

Returns the size (in Pages) of the Memory.

Example

let m = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();

assert_eq!(m.size(), Pages(1));

pub fn grow<IntoPages>(&self, delta: IntoPages) -> Result<Pages, MemoryError> where
    IntoPages: Into<Pages>, 

Grow memory by the specified amount of WebAssembly Pages and return the previous memory size.

Example

let m = Memory::new(&store, MemoryType::new(1, Some(3), false)).unwrap();
let p = m.grow(2).unwrap();

assert_eq!(p, Pages(1));
assert_eq!(m.size(), Pages(3));

Errors

Returns an error if memory can’t be grown by the specified amount of pages.

let m = Memory::new(&store, MemoryType::new(1, Some(1), false)).unwrap();

// This results in an error: `MemoryError::CouldNotGrow`.
let s = m.grow(1).unwrap();

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

Return a “view” of the currently accessible memory. By default, the view is unsynchronized, using regular memory accesses. You can force a memory view to use atomic accesses by calling the MemoryView::atomically method.

Notes:

This method is safe (as in, it won’t cause the host to crash or have UB), but it doesn’t obey rust’s rules involving data races, especially concurrent ones. Therefore, if this memory is shared between multiple threads, a single memory location can be mutated concurrently without synchronization.

Usage:

// Without synchronization.
let view: MemoryView<u8> = memory.view();
for byte in view[0x1000 .. 0x1010].iter().map(Cell::get) {
    println!("byte: {}", byte);
}

// With synchronization.
let atomic_view = view.atomically();
for byte in atomic_view[0x1000 .. 0x1010].iter().map(|atom| atom.load(Ordering::SeqCst)) {
    println!("byte: {}", byte);
}

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

Returns whether or not these two memories refer to the same data.

Example

let m = Memory::new(&store, MemoryType::new(1, None, false)).unwrap();

assert!(m.same(&m));

Trait Implementations

impl Clone for Memory

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Memory

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

Formats the value using the given formatter.

impl<'a> Exportable<'a> for Memory

fn to_export(&self) -> Export

This function is used when providedd the Extern as exportable, so it can be used while instantiating the Module.

fn get_self_from_extern(_extern: &'a Extern) -> Result<&'a Self, ExportError>

Implementation of how to get the export corresponding to the implementing type from an Instance by name.

fn into_weak_instance_ref(&mut self)

Convert the extern internally to hold a weak reference to the InstanceRef. This is useful for preventing cycles, for example for data stored in a type implementing WasmerEnv.

impl From<Memory> for Extern

fn from(r: Memory) -> Self

Performs the conversion.

impl MemoryUsage for Memory

fn size_of_val(&self, visited: &mut dyn MemoryUsageTracker) -> usize

Returns the size of the referenced value in bytes.