Struct patract_wasmi::MemoryRef

pub struct MemoryRef(_);

Reference to a memory (See MemoryInstance for details).

This reference has a reference-counting semantics.

Methods from Deref<Target = MemoryInstance>

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 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 patract_wasmi::MemoryInstance;
use patract_wasmi::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 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 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 erase(&self) -> Result<(), Error>

Set every byte in the entire linear memory to 0, preserving its size.

Might be useful for some optimization shenanigans.

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.

pub fn with_direct_access_mut<R, F: FnOnce(&mut [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. Proceed with caution.

pub fn direct_access<'a>(&'a self) -> impl AsRef<[u8]> + 'a

Provides direct access to the underlying memory buffer.

Panics

Any call that requires write access to memory (such as set, clear, etc) made while the returned value is alive will panic.

pub fn direct_access_mut<'a>(&'a self) -> impl AsMut<[u8]> + 'a

Provides direct mutable access to the underlying memory buffer.

Panics

Any call that requires either read or write access to memory (such as get, set, [copy], etc) made while the returned value is alive will panic. Proceed with caution.

Trait Implementations

impl Clone for MemoryRef

fn clone(&self) -> MemoryRef

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MemoryRef

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

Formats the value using the given formatter.

impl Deref for MemoryRef

type Target = MemoryInstance

The resulting type after dereferencing.

fn deref(&self) -> &MemoryInstance

Dereferences the value.