Struct wasmtime::Memory

pub struct Memory { /* fields omitted */ }

A WebAssembly linear memory.

WebAssembly memories represent a contiguous array of bytes that have a size that is always a multiple of the WebAssembly page size, currently 64 kilobytes.

WebAssembly memory is used for global data, statics in C/C++/Rust, shadow stack memory, etc. Accessing wasm memory is generally quite fast!

Memory and Clone

Memories are internally reference counted so you can clone a Memory. The cloning process only performs a shallow clone, so two cloned Memory instances are equivalent in their functionality.

Memory and threads

It is intended that Memory is safe to share between threads. At this time this is not implemented in wasmtime, however. This is planned to be implemented though!

Methods

impl Memory

pub fn new(store: &Store, ty: MemoryType) -> Memory

Creates a new WebAssembly memory given the configuration of ty.

The store argument is a general location for cache information, and otherwise the memory will immediately be allocated according to the type's configuration. All WebAssembly memory is initialized to zero.

pub fn ty(&self) -> &MemoryType

Returns the underlying type of this memory.

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

Returns this memory as a slice view that can be read natively in Rust.

Safety

This is an unsafe operation because there is no guarantee that the following operations do not happen concurrently while the slice is in use:

• Data could be modified by calling into a wasm module.
• Memory could be relocated through growth by calling into a wasm module.
• When threads are supported, non-atomic reads will race with other writes.

Extreme care need be taken when the data of a Memory is read. The above invariants all need to be upheld at a bare minimum, and in general you'll need to ensure that while you're looking at slice you're the only one who can possibly look at the slice and read/write it.

Be sure to keep in mind that Memory is reference counted, meaning that there may be other users of this Memory instance elsewhere in your program. Additionally Memory can be shared and used in any number of wasm instances, so calling any wasm code should be considered dangerous while you're holding a slice of memory.

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

Returns this memory as a slice view that can be read and written natively in Rust.

Safety

All of the same safety caveats of Memory::data_unchecked apply here, doubly so because this is returning a mutable slice! As a double-extra reminder, remember that Memory is reference counted, so you can very easily acquire two mutable slices by simply calling this function twice. Extreme caution should be used when using this method, and in general you probably want to result to unsafe accessors and the data methods below.

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

Returns the base pointer, in the host's address space, that the memory is located at.

When reading and manipulating memory be sure to read up on the caveats of Memory::data_unchecked to make sure that you can safely read/write the memory.

pub fn data_size(&self) -> usize

Returns the byte length of this memory.

The returned value will be a multiple of the wasm page size, 64k.

pub fn size(&self) -> u32

Returns the size, in pages, of this wasm memory.

pub fn grow(&self, delta: u32) -> Result<u32>

Grows this WebAssembly memory by delta pages.

This will attempt to add delta more pages of memory on to the end of this Memory instance. If successful this may relocate the memory and cause Memory::data_ptr to return a new value. Additionally previous slices into this memory may no longer be valid.

On success returns the number of pages this memory previously had before the growth succeeded.

Errors

Returns an error if memory could not be grown, for example if it exceeds the maximum limits of this memory.

Trait Implementations

impl Clone for Memory

fn clone(&self) -> Memory

Returns a copy of the value.

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

Performs copy-assignment from source.

impl From<Memory> for Extern

fn from(r: Memory) -> Self

Performs the conversion.