Struct susywasmi::MemoryInstance

pub struct MemoryInstance { /* fields omitted */ }

Runtime representation of a linear memory (or memory for short).

A memory is a contiguous, mutable array of raw bytes. Wasm code can load and store values from/to a linear memory at any byte address. A trap occurs if an access is not within the bounds of the current memory size.

A memory is created with an initial size but can be grown dynamically. The growth can be limited by specifying maximum size. The size of a memory is always a integer multiple of a page size - 64KiB.

At the moment, susywasm doesn't provide any way to shrink the memory.

Methods

impl MemoryInstance

pub fn alloc(initial: Pages, maximum: Option<Pages>) -> Result<MemoryRef, Error>

Allocate a memory instance.

The memory allocated with initial number of pages specified by initial. Minimal possible value for initial is 0 and maximum possible is 65536. (Since maximum addressible memory is 2³² = 4GiB = 65536 * 64KiB).

It is possible to limit maximum number of pages this memory instance can have by specifying maximum. If not specified, this memory instance would be able to allocate up to 4GiB.

Allocated memory is always zeroed.

Errors

Returns Err if:

• initial is greater than maximum
• either initial or maximum is greater than 65536.

pub fn initial(&self) -> Pages

Returns number of pages this MemoryInstance was created with.

pub fn maximum(&self) -> Option<Pages>

Returns maximum amount of pages this MemoryInstance can grow to.

Returns None if there is no limit set. Maximum memory size cannot exceed 65536 pages or 4GiB.

pub fn lowest_used(&self) -> u32

Returns lowest offset ever written or u32::max_value() if none.

pub fn reset_lowest_used(&self, addr: u32)

Resets tracked lowest offset.

pub fn current_size(&self) -> Pages

Returns current linear memory size.

Maximum memory size cannot exceed 65536 pages or 4GiB.

Example

To convert number of pages to number of bytes you can use the following code:

use susywasmi::MemoryInstance;
use susywasmi::memory_units::*;

let memory = MemoryInstance::alloc(Pages(1), None).unwrap();
let byte_size: Bytes = memory.current_size().into();
assert_eq!(
    byte_size,
    Bytes(65536),
);

pub fn used_size(&self) -> Bytes

Returns current used memory size in bytes. This is one more than the highest memory address that had been written to.

pub fn get_value<T: LittleEndianConvert>(&self, offset: u32) -> Result<T, Error>

Get value from memory at given offset.

pub fn get(&self, offset: u32, size: usize) -> Result<Vec<u8>, Error>

Copy data from memory at given offset.

This will allocate vector for you. If you can provide a mutable slice you can use get_into.

pub fn get_into(&self, offset: u32, target: &mut [u8]) -> Result<(), Error>

Copy data from given offset in the memory into target slice.

Errors

Returns Err if the specified region is out of bounds.

pub fn set(&self, offset: u32, value: &[u8]) -> Result<(), Error>

Copy data in the memory at given offset.

pub fn set_value<T: LittleEndianConvert>(
    &self,
    offset: u32,
    value: T
) -> Result<(), Error>

Copy value in the memory at given offset.

pub fn grow(&self, additional: Pages) -> Result<Pages, Error>

Increases the size of the linear memory by given number of pages. Returns previous memory size if succeeds.

Errors

Returns Err if attempted to allocate more memory than permited by the limit.

pub fn copy(
    &self,
    src_offset: usize,
    dst_offset: usize,
    len: usize
) -> Result<(), Error>

Copy contents of one memory region to another.

Semantically equivalent to memmove.

Errors

Returns Err if either of specified regions is out of bounds.

pub fn copy_nonoverlapping(
    &self,
    src_offset: usize,
    dst_offset: usize,
    len: usize
) -> Result<(), Error>

Copy contents of one memory region to another (non-overlapping version).

Semantically equivalent to memcpy. but returns Error if source overlaping with destination.

Errors

Returns Err if:

• either of specified regions is out of bounds,
• these regions overlaps.

pub fn transfer(
    src: &MemoryRef,
    src_offset: usize,
    dst: &MemoryRef,
    dst_offset: usize,
    len: usize
) -> Result<(), Error>

Copy memory between two (possibly distinct) memory instances.

If the same memory instance passed as src and dst then usual copy will be used.

pub fn clear(&self, offset: usize, new_val: u8, len: usize) -> Result<(), Error>

Fill the memory region with the specified value.

Semantically equivalent to memset.

Errors

Returns Err if the specified region is out of bounds.

pub fn zero(&self, offset: usize, len: usize) -> Result<(), Error>

Fill the specified memory region with zeroes.

Errors

Returns Err if the specified region is out of bounds.

pub fn with_direct_access<R, F: FnOnce(&[u8]) -> R>(&self, f: F) -> R

Provides direct access to the underlying memory buffer.

Panics

Any call that requires write access to memory (such as set, clear, etc) made within the closure will panic. Note that the buffer size may be arbitraty. Proceed with caution.

pub fn with_direct_access_mut<R, F: FnOnce(&mut Vec<u8>) -> R>(&self, f: F) -> R

Provides direct mutable access to the underlying memory buffer.

Panics

Any calls that requires either read or write access to memory (such as get, set, copy, etc) made within the closure will panic. Note that the buffer size may be arbitraty. The closure may however resize it. Proceed with caution.

Trait Implementations

impl Debug for MemoryInstance

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

Formats the value using the given formatter.