Struct Memory 

pub struct Memory(/* private fields */);

Newtype wrapper around wasmtime::Memory.

Implementations

impl Memory

pub fn new(inner: Memory) -> Self

Create a wasm_runtime_layer::Memory-compatible Memory from a wasmtime::Memory.

pub fn into_inner(self) -> Memory

Consume a Memory to obtain the inner wasmtime::Memory.

Methods from Deref<Target = Memory>

pub fn ty(&self, store: impl AsContext) -> MemoryType

Returns the underlying type of this memory.

Panics

Panics if this memory doesn’t belong to store.

Examples

let engine = Engine::default();
let mut store = Store::new(&engine, ());
let module = Module::new(&engine, "(module (memory (export \"mem\") 1))")?;
let instance = Instance::new(&mut store, &module, &[])?;
let memory = instance.get_memory(&mut store, "mem").unwrap();
let ty = memory.ty(&store);
assert_eq!(ty.minimum(), 1);

pub fn read( &self, store: impl AsContext, offset: usize, buffer: &mut [u8], ) -> Result<(), MemoryAccessError>

Safely reads memory contents at the given offset into a buffer.

The entire buffer will be filled.

If offset + buffer.len() exceed the current memory capacity, then the buffer is left untouched and a MemoryAccessError is returned.

Errors

This function will return an OutOfMemory error when memory allocation fails. See the OutOfMemory type’s documentation for details on Wasmtime’s out-of-memory handling.

Panics

Panics if this memory doesn’t belong to store.

pub fn write( &self, store: impl AsContextMut, offset: usize, buffer: &[u8], ) -> Result<(), MemoryAccessError>

Safely writes contents of a buffer to this memory at the given offset.

If the offset + buffer.len() exceeds the current memory capacity, then none of the buffer is written to memory and a MemoryAccessError is returned.

Errors

This function will return an OutOfMemory error when memory allocation fails. See the OutOfMemory type’s documentation for details on Wasmtime’s out-of-memory handling.

Panics

Panics if this memory doesn’t belong to store.

pub fn data<'a, T>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a [u8]

where T: 'static,

Returns this memory as a native Rust slice.

Note that this method will consider the entire store context provided as borrowed for the duration of the lifetime of the returned slice.

Panics

Panics if this memory doesn’t belong to store.

pub fn data_mut<'a, T>( &self, store: impl Into<StoreContextMut<'a, T>>, ) -> &'a mut [u8]

where T: 'static,

Returns this memory as a native Rust mutable slice.

Note that this method will consider the entire store context provided as borrowed for the duration of the lifetime of the returned slice.

Panics

Panics if this memory doesn’t belong to store.

pub fn data_and_store_mut<'a, T>( &self, store: impl Into<StoreContextMut<'a, T>>, ) -> (&'a mut [u8], &'a mut T)

where T: 'static,

Same as Memory::data_mut, but also returns the T from the StoreContextMut.

This method can be used when you want to simultaneously work with the T in the store as well as the memory behind this Memory. Using Memory::data_mut would consider the entire store borrowed, whereas this method allows the Rust compiler to see that the borrow of this memory and the borrow of T are disjoint.

Panics

Panics if this memory doesn’t belong to store.

pub fn data_ptr(&self, store: impl AsContext) -> *mut u8

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

For more information and examples see the documentation on the Memory type.

Panics

Panics if this memory doesn’t belong to store.

pub fn data_size(&self, store: impl AsContext) -> usize

Returns the byte length of this memory.

WebAssembly memories are made up of a whole number of pages, so the byte size returned will always be a multiple of this memory’s page size. Note that different Wasm memories may have different page sizes. You can get a memory’s page size via the Memory::page_size method.

By default the page size is 64KiB (aka 0x10000, 2**16, 1<<16, or 65536) but the custom-page-sizes proposal allows a memory to opt into a page size of 1. Future extensions might allow any power of two as a page size.

For more information and examples see the documentation on the Memory type.

Panics

Panics if this memory doesn’t belong to store.

pub fn size(&self, store: impl AsContext) -> u64

Returns the size, in units of pages, of this Wasm memory.

WebAssembly memories are made up of a whole number of pages, so the byte size returned will always be a multiple of this memory’s page size. Note that different Wasm memories may have different page sizes. You can get a memory’s page size via the Memory::page_size method.

By default the page size is 64KiB (aka 0x10000, 2**16, 1<<16, or 65536) but the custom-page-sizes proposal allows a memory to opt into a page size of 1. Future extensions might allow any power of two as a page size.

Panics

Panics if this memory doesn’t belong to store.

pub fn page_size(&self, store: impl AsContext) -> u64

Returns the size of a page, in bytes, for this memory.

WebAssembly memories are made up of a whole number of pages, so the byte size (as returned by Memory::data_size) will always be a multiple of their page size. Different Wasm memories may have different page sizes.

By default this is 64KiB (aka 0x10000, 2**16, 1<<16, or 65536) but the custom-page-sizes proposal allows opting into a page size of 1. Future extensions might allow any power of two as a page size.

pub fn page_size_log2(&self, store: impl AsContext) -> u8

Returns the log2 of this memory’s page size, in bytes.

WebAssembly memories are made up of a whole number of pages, so the byte size (as returned by Memory::data_size) will always be a multiple of their page size. Different Wasm memories may have different page sizes.

By default the page size is 64KiB (aka 0x10000, 2**16, 1<<16, or 65536) but the custom-page-sizes proposal allows opting into a page size of 1. Future extensions might allow any power of two as a page size.

pub fn grow(&self, store: impl AsContextMut, delta: u64) -> Result<u64, Error>

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 any unsafely constructed slices into this memory may no longer be valid.

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

Note that, by default, a WebAssembly memory’s page size is 64KiB (aka 65536 or 2¹⁶). The custom-page-sizes proposal allows Wasm memories to opt into a page size of one byte (and this may be further relaxed to any power of two in a future extension).

Errors

Returns an error if memory could not be grown, for example if it exceeds the maximum limits of this memory. A ResourceLimiter is another example of preventing a memory to grow.

This function will return an error if the Store has a ResourceLimiterAsync (see also: Store::limiter_async. When using an async resource limiter, use [Memory::grow_async] instead.

This function will return an OutOfMemory error when memory allocation fails. See the OutOfMemory type’s documentation for details on Wasmtime’s out-of-memory handling.

Panics

Panics if this memory doesn’t belong to store.

Examples

let engine = Engine::default();
let mut store = Store::new(&engine, ());
let module = Module::new(&engine, "(module (memory (export \"mem\") 1 2))")?;
let instance = Instance::new(&mut store, &module, &[])?;
let memory = instance.get_memory(&mut store, "mem").unwrap();

assert_eq!(memory.size(&store), 1);
assert_eq!(memory.grow(&mut store, 1)?, 1);
assert_eq!(memory.size(&store), 2);
assert!(memory.grow(&mut store, 1).is_err());
assert_eq!(memory.size(&store), 2);
assert_eq!(memory.grow(&mut store, 0)?, 2);

Trait Implementations

impl AsMut<Memory> for Memory

fn as_mut(&mut self) -> &mut Memory

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<Memory> for Memory

fn as_mut(&mut self) -> &mut Memory

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Memory> for Memory

fn as_ref(&self) -> &Memory

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Memory> for Memory

fn as_ref(&self) -> &Memory

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Memory

fn clone(&self) -> Memory

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for Memory

type Target = Memory

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Memory

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<Memory> for Memory

fn from(inner: Memory) -> Self

Converts to this type from the input type.

impl From<Memory> for Memory

fn from(wrapper: Memory) -> Self

Converts to this type from the input type.

impl RefCast for Memory

type From = Memory

fn ref_cast(_from: &Self::From) -> &Self

fn ref_cast_mut(_from: &mut Self::From) -> &mut Self

impl WasmMemory<Engine> for Memory

fn new(ctx: impl AsContextMut<Engine>, ty: MemoryType) -> Result<Self>

Creates a new linear memory to the store.

fn ty(&self, ctx: impl AsContext<Engine>) -> MemoryType

Returns the memory type of the linear memory.

fn grow(&self, ctx: impl AsContextMut<Engine>, additional: u32) -> Result<u32>

Grows the linear memory by the given amount of new pages.

fn current_pages(&self, ctx: impl AsContext<Engine>) -> u32

Returns the amount of pages in use by the linear memory.

fn read( &self, ctx: impl AsContext<Engine>, offset: usize, buffer: &mut [u8], ) -> Result<()>

Reads n bytes from memory[offset..offset+n] into buffer where n is the length of buffer.

fn write( &self, ctx: impl AsContextMut<Engine>, offset: usize, buffer: &[u8], ) -> Result<()>

Writes n bytes to memory[offset..offset+n] from buffer where n if the length of buffer.