Struct wasmtime::SharedMemory

pub struct SharedMemory(_, _);

A constructor for externally-created shared memory.

The threads proposal adds the concept of “shared memory” to WebAssembly. This is much the same as a Wasm linear memory (i.e., Memory), but can be used concurrently by multiple agents. Because these agents may execute in different threads, SharedMemory must be thread-safe.

When the threads proposal is enabled, there are multiple ways to construct shared memory:

1. for imported shared memory, e.g., (import "env" "memory" (memory 1 1 shared)), the user must supply a SharedMemory with the externally-created memory as an import to the instance–e.g., shared_memory.into().
2. for private or exported shared memory, e.g., (export "env" "memory" (memory 1 1 shared)), Wasmtime will create the memory internally during instantiation–access using Instance::get_shared_memory().

Examples

let mut config = Config::new();
config.wasm_threads(true);
let engine = Engine::new(&config)?;
let mut store = Store::new(&engine, ());

let shared_memory = SharedMemory::new(&engine, MemoryType::shared(1, 2))?;
let module = Module::new(&engine, r#"(module (memory (import "" "") 1 2 shared))"#)?;
let instance = Instance::new(&mut store, &module, &[shared_memory.into()])?;
// ...

Implementations

impl SharedMemory

pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self>

Construct a SharedMemory by providing both the minimum and maximum number of 64K-sized pages. This call allocates the necessary pages on the system.

pub fn ty(&self) -> MemoryType

Return the type of the shared memory.

pub fn size(&self) -> u64

Returns the size, in WebAssembly pages, of this wasm 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.

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

pub fn data(&self) -> *mut [u8]

Return access to the available portion of the shared memory.

Because the memory is shared, it is possible that this memory is being modified in other threads–in other words, the data can change at any time. Users of this function must manage synchronization and locking to this region of memory themselves.

Not only can the data change, but the length of this region can change as well. Other threads can call memory.grow operations that will extend the region length but–importantly–this will not be reflected in the size of region returned by this function.

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

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.

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.

Trait Implementations

impl Clone for SharedMemory

fn clone(&self) -> SharedMemory

Returns a copy of the value.

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

Performs copy-assignment from source.

impl From<SharedMemory> for Extern

fn from(r: SharedMemory) -> Self

Converts to this type from the input type.