Struct wasmtime::SharedMemory
source · pub struct SharedMemory { /* private fields */ }
Expand description
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:
- for imported shared memory, e.g.,
(import "env" "memory" (memory 1 1 shared))
, the user must supply aSharedMemory
with the externally-created memory as an import to the instance–e.g.,shared_memory.into()
. - for private or exported shared memory, e.g.,
(export "env" "memory" (memory 1 1 shared))
, Wasmtime will create the memory internally during instantiation–access usingInstance::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§
sourcepub fn ty(&self) -> MemoryType
pub fn ty(&self) -> MemoryType
Return the type of the shared memory.
sourcepub fn page_size(&self) -> u32
pub fn page_size(&self) -> u32
Returns the size of a page, in bytes, for this memory.
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.
sourcepub fn data_size(&self) -> usize
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.
sourcepub fn data(&self) -> &[UnsafeCell<u8>]
pub fn data(&self) -> &[UnsafeCell<u8>]
Return access to the available portion of the shared memory.
The slice returned represents the region of accessible memory at the time that this function was called. The contents of the returned slice will reflect concurrent modifications happening on other threads.
§Safety
The returned slice is valid for the entire duration of the lifetime of
this instance of SharedMemory
. The base pointer of a shared memory
does not change. This SharedMemory
may grow further after this
function has been called, but the slice returned will not grow.
Concurrent modifications may be happening to the data returned on other
threads. The UnsafeCell<u8>
represents that safe access to the
contents of the slice is not possible through normal loads and stores.
The memory returned must be accessed safely through the Atomic*
types
in the std::sync::atomic
module. Casting to those types must
currently be done unsafely.
sourcepub fn grow(&self, delta: u64) -> Result<u64>
pub fn grow(&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.
sourcepub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap>
pub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap>
Equivalent of the WebAssembly memory.atomic.notify
instruction for
this shared memory.
This method allows embedders to notify threads blocked on the specified
addr
, an index into wasm linear memory. Threads could include
wasm threads blocked on a memory.atomic.wait*
instruction or embedder
threads blocked on SharedMemory::atomic_wait32
, for example.
The count
argument is the number of threads to wake up.
This function returns the number of threads awoken.
§Errors
This function will return an error if addr
is not within bounds or
not aligned to a 4-byte boundary.
sourcepub fn atomic_wait32(
&self,
addr: u64,
expected: u32,
timeout: Option<Duration>,
) -> Result<WaitResult, Trap>
pub fn atomic_wait32( &self, addr: u64, expected: u32, timeout: Option<Duration>, ) -> Result<WaitResult, Trap>
Equivalent of the WebAssembly memory.atomic.wait32
instruction for
this shared memory.
This method allows embedders to block the current thread until notified
via the memory.atomic.notify
instruction or the
SharedMemory::atomic_notify
method, enabling synchronization with
the wasm guest as desired.
The expected
argument is the expected 32-bit value to be stored at
the byte address addr
specified. The addr
specified is an index
into this linear memory.
The optional timeout
argument is the maximum amount of time to block
the current thread. If not specified the thread may sleep indefinitely.
This function returns one of three possible values:
WaitResult::Ok
- this function, loaded the value ataddr
, found it was equal toexpected
, and then blocked (all as one atomic operation). The thread was then awoken with amemory.atomic.notify
instruction or theSharedMemory::atomic_notify
method.WaitResult::Mismatch
- the value ataddr
was loaded but was not equal toexpected
so the thread did not block and immediately returned.WaitResult::TimedOut
- all the steps ofOk
happened, except this thread was woken up due to a timeout.
This function will not return due to spurious wakeups.
§Errors
This function will return an error if addr
is not within bounds or
not aligned to a 4-byte boundary.
sourcepub fn atomic_wait64(
&self,
addr: u64,
expected: u64,
timeout: Option<Duration>,
) -> Result<WaitResult, Trap>
pub fn atomic_wait64( &self, addr: u64, expected: u64, timeout: Option<Duration>, ) -> Result<WaitResult, Trap>
Equivalent of the WebAssembly memory.atomic.wait64
instruction for
this shared memory.
For more information see SharedMemory::atomic_wait32
.
§Errors
Returns the same error as SharedMemory::atomic_wait32
except that
the specified address must be 8-byte aligned instead of 4-byte aligned.
Trait Implementations§
source§fn clone(&self) -> SharedMemory
fn clone(&self) -> SharedMemory
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§fn from(r: SharedMemory) -> Self
fn from(r: SharedMemory) -> Self
Auto Trait Implementations§
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more