wasmtime/runtime/memory.rs
1use crate::Trap;
2use crate::prelude::*;
3use crate::runtime::vm::{self, ExportMemory};
4use crate::store::{StoreInstanceId, StoreOpaque, StoreResourceLimiter};
5use crate::trampoline::generate_memory_export;
6#[cfg(feature = "async")]
7use crate::vm::VMStore;
8use crate::{AsContext, AsContextMut, Engine, MemoryType, StoreContext, StoreContextMut};
9use alloc::sync::Arc;
10use core::any::Any;
11use core::cell::UnsafeCell;
12use core::fmt;
13use core::ops::Range;
14use core::slice;
15use core::time::Duration;
16use wasmtime_environ::{DefinedMemoryIndex, MemoryTunables};
17
18pub use crate::runtime::vm::WaitResult;
19
20/// Error for out of bounds [`Memory`] access.
21#[derive(Debug)]
22#[non_exhaustive]
23pub struct MemoryAccessError {
24 // Keep struct internals private for future extensibility.
25 _private: (),
26}
27
28impl fmt::Display for MemoryAccessError {
29 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
30 write!(f, "out of bounds memory access")
31 }
32}
33
34impl core::error::Error for MemoryAccessError {}
35
36/// A WebAssembly linear memory.
37///
38/// WebAssembly memories represent a contiguous array of bytes that have a size
39/// that is always a multiple of the WebAssembly page size, currently 64
40/// kilobytes.
41///
42/// WebAssembly memory is used for global data (not to be confused with wasm
43/// `global` items), statics in C/C++/Rust, shadow stack memory, etc. Accessing
44/// wasm memory is generally quite fast.
45///
46/// Memories, like other wasm items, are owned by a [`Store`](crate::Store).
47///
48/// # `Memory` and Safety
49///
50/// Linear memory is a lynchpin of safety for WebAssembly. In Wasmtime there are
51/// safe methods of interacting with a [`Memory`]:
52///
53/// * [`Memory::read`]
54/// * [`Memory::write`]
55/// * [`Memory::data`]
56/// * [`Memory::data_mut`]
57///
58/// Note that all of these consider the entire store context as borrowed for the
59/// duration of the call or the duration of the returned slice. This largely
60/// means that while the function is running you'll be unable to borrow anything
61/// else from the store. This includes getting access to the `T` on
62/// [`Store<T>`](crate::Store), but it also means that you can't recursively
63/// call into WebAssembly for instance.
64///
65/// If you'd like to dip your toes into handling [`Memory`] in a more raw
66/// fashion (e.g. by using raw pointers or raw slices), then there's a few
67/// important points to consider when doing so:
68///
69/// * Any recursive calls into WebAssembly can possibly modify any byte of the
70/// entire memory. This means that whenever wasm is called Rust can't have any
71/// long-lived borrows live across the wasm function call. Slices like `&mut
72/// [u8]` will be violated because they're not actually exclusive at that
73/// point, and slices like `&[u8]` are also violated because their contents
74/// may be mutated.
75///
76/// * WebAssembly memories can grow, and growth may change the base pointer.
77/// This means that even holding a raw pointer to memory over a wasm function
78/// call is also incorrect. Anywhere in the function call the base address of
79/// memory may change. Note that growth can also be requested from the
80/// embedding API as well.
81///
82/// As a general rule of thumb it's recommended to stick to the safe methods of
83/// [`Memory`] if you can. It's not advised to use raw pointers or `unsafe`
84/// operations because of how easy it is to accidentally get things wrong.
85///
86/// Some examples of safely interacting with memory are:
87///
88/// ```rust
89/// use wasmtime::{Memory, Store, MemoryAccessError};
90///
91/// // Memory can be read and written safely with the `Memory::read` and
92/// // `Memory::write` methods.
93/// // An error is returned if the copy did not succeed.
94/// fn safe_examples(mem: Memory, store: &mut Store<()>) -> Result<(), MemoryAccessError> {
95/// let offset = 5;
96/// mem.write(&mut *store, offset, b"hello")?;
97/// let mut buffer = [0u8; 5];
98/// mem.read(&store, offset, &mut buffer)?;
99/// assert_eq!(b"hello", &buffer);
100///
101/// // Note that while this is safe care must be taken because the indexing
102/// // here may panic if the memory isn't large enough.
103/// assert_eq!(&mem.data(&store)[offset..offset + 5], b"hello");
104/// mem.data_mut(&mut *store)[offset..offset + 5].copy_from_slice(b"bye!!");
105///
106/// Ok(())
107/// }
108/// ```
109///
110/// It's worth also, however, covering some examples of **incorrect**,
111/// **unsafe** usages of `Memory`. Do not do these things!
112///
113/// ```rust
114/// use wasmtime::{Memory, Result, Store};
115///
116/// // NOTE: All code in this function is not safe to execute and may cause
117/// // segfaults/undefined behavior at runtime. Do not copy/paste these examples
118/// // into production code!
119/// unsafe fn unsafe_examples(mem: Memory, store: &mut Store<()>) -> Result<()> {
120/// // First and foremost, any borrow can be invalidated at any time via the
121/// // `Memory::grow` function. This can relocate memory which causes any
122/// // previous pointer to be possibly invalid now.
123/// unsafe {
124/// let pointer: &u8 = &*mem.data_ptr(&store);
125/// mem.grow(&mut *store, 1)?; // invalidates `pointer`!
126/// // println!("{}", *pointer); // FATAL: use-after-free
127/// }
128///
129/// // Note that the use-after-free also applies to slices, whether they're
130/// // slices of bytes or strings.
131/// unsafe {
132/// let mem_slice = std::slice::from_raw_parts(
133/// mem.data_ptr(&store),
134/// mem.data_size(&store),
135/// );
136/// let slice: &[u8] = &mem_slice[0x100..0x102];
137/// mem.grow(&mut *store, 1)?; // invalidates `slice`!
138/// // println!("{:?}", slice); // FATAL: use-after-free
139/// }
140///
141/// // The `Memory` type may be stored in other locations, so if you hand
142/// // off access to the `Store` then those locations may also call
143/// // `Memory::grow` or similar, so it's not enough to just audit code for
144/// // calls to `Memory::grow`.
145/// unsafe {
146/// let pointer: &u8 = &*mem.data_ptr(&store);
147/// some_other_function(store); // may invalidate `pointer` through use of `store`
148/// // println!("{:?}", pointer); // FATAL: maybe a use-after-free
149/// }
150///
151/// // An especially subtle aspect of accessing a wasm instance's memory is
152/// // that you need to be extremely careful about aliasing. Anyone at any
153/// // time can call `data_unchecked()` or `data_unchecked_mut()`, which
154/// // means you can easily have aliasing mutable references:
155/// unsafe {
156/// let ref1: &u8 = &*mem.data_ptr(&store).add(0x100);
157/// let ref2: &mut u8 = &mut *mem.data_ptr(&store).add(0x100);
158/// // *ref2 = *ref1; // FATAL: violates Rust's aliasing rules
159/// }
160///
161/// Ok(())
162/// }
163/// # fn some_other_function(store: &mut Store<()>) {}
164/// ```
165///
166/// Overall there's some general rules of thumb when unsafely working with
167/// `Memory` and getting raw pointers inside of it:
168///
169/// * If you never have a "long lived" pointer into memory, you're likely in the
170/// clear. Care still needs to be taken in threaded scenarios or when/where
171/// data is read, but you'll be shielded from many classes of issues.
172/// * Long-lived pointers must always respect Rust'a aliasing rules. It's ok for
173/// shared borrows to overlap with each other, but mutable borrows must
174/// overlap with nothing.
175/// * Long-lived pointers are only valid if they're not invalidated for their
176/// lifetime. This means that [`Store`](crate::Store) isn't used to reenter
177/// wasm or the memory itself is never grown or otherwise modified/aliased.
178///
179/// At this point it's worth reiterating again that unsafely working with
180/// `Memory` is pretty tricky and not recommended! It's highly recommended to
181/// use the safe methods to interact with [`Memory`] whenever possible.
182///
183/// ## `Memory` Safety and Threads
184///
185/// Currently the `wasmtime` crate does not implement the wasm threads proposal,
186/// but it is planned to do so. It may be interesting to readers to see how this
187/// affects memory safety and what was previously just discussed as well.
188///
189/// Once threads are added into the mix, all of the above rules still apply.
190/// There's an additional consideration that all reads and writes can happen
191/// concurrently, though. This effectively means that any borrow into wasm
192/// memory are virtually never safe to have.
193///
194/// Mutable pointers are fundamentally unsafe to have in a concurrent scenario
195/// in the face of arbitrary wasm code. Only if you dynamically know for sure
196/// that wasm won't access a region would it be safe to construct a mutable
197/// pointer. Additionally even shared pointers are largely unsafe because their
198/// underlying contents may change, so unless `UnsafeCell` in one form or
199/// another is used everywhere there's no safety.
200///
201/// One important point about concurrency is that while [`Memory::grow`] can
202/// happen concurrently it will never relocate the base pointer. Shared
203/// memories must always have a maximum size and they will be preallocated such
204/// that growth will never relocate the base pointer. The current size of the
205/// memory may still change over time though.
206///
207/// Overall the general rule of thumb for shared memories is that you must
208/// atomically read and write everything. Nothing can be borrowed and everything
209/// must be eagerly copied out. This means that [`Memory::data`] and
210/// [`Memory::data_mut`] won't work in the future (they'll probably return an
211/// error) for shared memories when they're implemented. When possible it's
212/// recommended to use [`Memory::read`] and [`Memory::write`] which will still
213/// be provided.
214#[derive(Copy, Clone, Debug)]
215#[repr(C)] // here for the C API
216pub struct Memory {
217 /// The internal store instance that this memory belongs to.
218 instance: StoreInstanceId,
219 /// The index of the memory, within `instance` above, that this memory
220 /// refers to.
221 index: DefinedMemoryIndex,
222}
223
224// Double-check that the C representation in `extern.h` matches our in-Rust
225// representation here in terms of size/alignment/etc.
226const _: () = {
227 #[repr(C)]
228 struct Tmp(u64, u32);
229 #[repr(C)]
230 struct C(Tmp, u32);
231 assert!(core::mem::size_of::<C>() == core::mem::size_of::<Memory>());
232 assert!(core::mem::align_of::<C>() == core::mem::align_of::<Memory>());
233 assert!(core::mem::offset_of!(Memory, instance) == 0);
234};
235
236impl Memory {
237 /// Creates a new WebAssembly memory given the configuration of `ty`.
238 ///
239 /// The `store` argument will be the owner of the returned [`Memory`]. All
240 /// WebAssembly memory is initialized to zero.
241 ///
242 /// # Panics
243 ///
244 /// This function will panic if the [`Store`](`crate::Store`) has a
245 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
246 /// [`Store::limiter_async`](`crate::Store::limiter_async`)). When
247 /// using an async resource limiter, use [`Memory::new_async`] instead.
248 ///
249 /// # Examples
250 ///
251 /// ```
252 /// # use wasmtime::*;
253 /// # fn main() -> Result<()> {
254 /// let engine = Engine::default();
255 /// let mut store = Store::new(&engine, ());
256 ///
257 /// let memory_ty = MemoryType::new(1, None)?;
258 /// let memory = Memory::new(&mut store, memory_ty)?;
259 ///
260 /// let module = Module::new(&engine, "(module (memory (import \"\" \"\") 1))")?;
261 /// let instance = Instance::new(&mut store, &module, &[memory.into()])?;
262 /// // ...
263 /// # Ok(())
264 /// # }
265 /// ```
266 ///
267 /// # Errors
268 ///
269 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
270 /// memory allocation fails. See the `OutOfMemory` type's documentation for
271 /// details on Wasmtime's out-of-memory handling.
272 pub fn new(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
273 let (mut limiter, store) = store
274 .as_context_mut()
275 .0
276 .validate_sync_resource_limiter_and_store_opaque()?;
277 vm::assert_ready(Self::_new(store, limiter.as_mut(), ty))
278 }
279
280 /// Async variant of [`Memory::new`]. You must use this variant with
281 /// [`Store`](`crate::Store`)s which have a
282 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
283 ///
284 /// # Panics
285 ///
286 /// This function will panic when used with a non-async
287 /// [`Store`](`crate::Store`).
288 ///
289 /// # Errors
290 ///
291 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
292 /// memory allocation fails. See the `OutOfMemory` type's documentation for
293 /// details on Wasmtime's out-of-memory handling.
294 #[cfg(feature = "async")]
295 pub async fn new_async(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
296 let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();
297 Self::_new(store, limiter.as_mut(), ty).await
298 }
299
300 /// Helper function for attaching the memory to a "frankenstein" instance
301 async fn _new(
302 store: &mut StoreOpaque,
303 limiter: Option<&mut StoreResourceLimiter<'_>>,
304 ty: MemoryType,
305 ) -> Result<Memory> {
306 if ty.is_shared() {
307 bail!("shared memories must be created through `SharedMemory`")
308 }
309 store.bump_memory_count()?;
310 Ok(generate_memory_export(store, limiter, &ty, None)
311 .await?
312 .unshared()
313 .unwrap())
314 }
315
316 /// Returns the underlying type of this memory.
317 ///
318 /// # Panics
319 ///
320 /// Panics if this memory doesn't belong to `store`.
321 ///
322 /// # Examples
323 ///
324 /// ```
325 /// # use wasmtime::*;
326 /// # fn main() -> Result<()> {
327 /// let engine = Engine::default();
328 /// let mut store = Store::new(&engine, ());
329 /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1))")?;
330 /// let instance = Instance::new(&mut store, &module, &[])?;
331 /// let memory = instance.get_memory(&mut store, "mem").unwrap();
332 /// let ty = memory.ty(&store);
333 /// assert_eq!(ty.minimum(), 1);
334 /// # Ok(())
335 /// # }
336 /// ```
337 pub fn ty(&self, store: impl AsContext) -> MemoryType {
338 let store = store.as_context();
339 MemoryType::from_wasmtime_memory(self.wasmtime_ty(store.0))
340 }
341
342 /// Safely reads memory contents at the given offset into a buffer.
343 ///
344 /// The entire buffer will be filled.
345 ///
346 /// If `offset + buffer.len()` exceed the current memory capacity, then the
347 /// buffer is left untouched and a [`MemoryAccessError`] is returned.
348 ///
349 /// # Errors
350 ///
351 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
352 /// memory allocation fails. See the `OutOfMemory` type's documentation for
353 /// details on Wasmtime's out-of-memory handling.
354 ///
355 /// # Panics
356 ///
357 /// Panics if this memory doesn't belong to `store`.
358 pub fn read(
359 &self,
360 store: impl AsContext,
361 offset: usize,
362 buffer: &mut [u8],
363 ) -> Result<(), MemoryAccessError> {
364 let store = store.as_context();
365 let slice = self
366 .data(&store)
367 .get(offset..)
368 .and_then(|s| s.get(..buffer.len()))
369 .ok_or(MemoryAccessError { _private: () })?;
370 buffer.copy_from_slice(slice);
371 Ok(())
372 }
373
374 /// Safely writes contents of a buffer to this memory at the given offset.
375 ///
376 /// If the `offset + buffer.len()` exceeds the current memory capacity, then
377 /// none of the buffer is written to memory and a [`MemoryAccessError`] is
378 /// returned.
379 ///
380 /// # Errors
381 ///
382 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
383 /// memory allocation fails. See the `OutOfMemory` type's documentation for
384 /// details on Wasmtime's out-of-memory handling.
385 ///
386 /// # Panics
387 ///
388 /// Panics if this memory doesn't belong to `store`.
389 pub fn write(
390 &self,
391 mut store: impl AsContextMut,
392 offset: usize,
393 buffer: &[u8],
394 ) -> Result<(), MemoryAccessError> {
395 let mut context = store.as_context_mut();
396 self.data_mut(&mut context)
397 .get_mut(offset..)
398 .and_then(|s| s.get_mut(..buffer.len()))
399 .ok_or(MemoryAccessError { _private: () })?
400 .copy_from_slice(buffer);
401 Ok(())
402 }
403
404 /// Returns the [`LinearMemory`] backing this memory if it is of the concrete type `M`.
405 ///
406 /// This is intended for embedders that create memories with a custom
407 /// [`MemoryCreator`] (see [`Config::with_host_memory`](crate::Config::with_host_memory))
408 /// and need to inspect the created [`LinearMemory`] object after instantiation.
409 ///
410 /// Returns `None` if the memory is not of type `M`.
411 /// Keeping the concrete `M` returned by a [`MemoryCreator`] private
412 /// ensures that no other code with access to the store can obtain it.
413 ///
414 /// Note that this method will consider the entire store context provided as
415 /// borrowed for the duration of the lifetime of the returned reference.
416 ///
417 /// # Panics
418 ///
419 /// Panics if this memory doesn't belong to `store`.
420 pub fn linear_memory<'a, M: LinearMemory, T: 'static>(
421 &self,
422 store: impl Into<StoreContext<'a, T>>,
423 ) -> Option<&'a M> {
424 let store: &'a StoreOpaque = store.into().0;
425 let memory: &'a dyn Any = store[self.instance]
426 .get_defined_memory(self.index)
427 .as_linear_memory()?;
428 memory.downcast_ref()
429 }
430
431 /// Returns this memory as a native Rust slice.
432 ///
433 /// Note that this method will consider the entire store context provided as
434 /// borrowed for the duration of the lifetime of the returned slice.
435 ///
436 /// # Panics
437 ///
438 /// Panics if this memory doesn't belong to `store`.
439 pub fn data<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a [u8] {
440 unsafe {
441 let store = store.into();
442 let definition = store[self.instance].memory(self.index);
443 debug_assert!(!self.ty(store).is_shared());
444 slice::from_raw_parts(definition.base.as_ptr(), definition.current_length())
445 }
446 }
447
448 /// Returns this memory as a native Rust mutable slice.
449 ///
450 /// Note that this method will consider the entire store context provided as
451 /// borrowed for the duration of the lifetime of the returned slice.
452 ///
453 /// # Panics
454 ///
455 /// Panics if this memory doesn't belong to `store`.
456 pub fn data_mut<'a, T: 'static>(
457 &self,
458 store: impl Into<StoreContextMut<'a, T>>,
459 ) -> &'a mut [u8] {
460 unsafe {
461 let store = store.into();
462 let definition = store[self.instance].memory(self.index);
463 debug_assert!(!self.ty(store).is_shared());
464 slice::from_raw_parts_mut(definition.base.as_ptr(), definition.current_length())
465 }
466 }
467
468 /// Same as [`Memory::data_mut`], but also returns the `T` from the
469 /// [`StoreContextMut`].
470 ///
471 /// This method can be used when you want to simultaneously work with the
472 /// `T` in the store as well as the memory behind this [`Memory`]. Using
473 /// [`Memory::data_mut`] would consider the entire store borrowed, whereas
474 /// this method allows the Rust compiler to see that the borrow of this
475 /// memory and the borrow of `T` are disjoint.
476 ///
477 /// # Panics
478 ///
479 /// Panics if this memory doesn't belong to `store`.
480 pub fn data_and_store_mut<'a, T: 'static>(
481 &self,
482 store: impl Into<StoreContextMut<'a, T>>,
483 ) -> (&'a mut [u8], &'a mut T) {
484 // Note the unsafety here. Our goal is to simultaneously borrow the
485 // memory and custom data from `store`, and the store it's connected
486 // to. Rust will not let us do that, however, because we must call two
487 // separate methods (both of which borrow the whole `store`) and one of
488 // our borrows is mutable (the custom data).
489 //
490 // This operation, however, is safe because these borrows do not overlap
491 // and in the process of borrowing them mutability doesn't actually
492 // touch anything. This is akin to mutably borrowing two indices in an
493 // array, which is safe so long as the indices are separate.
494 unsafe {
495 let mut store = store.into();
496 let data = &mut *(store.data_mut() as *mut T);
497 (self.data_mut(store), data)
498 }
499 }
500
501 /// Returns `range` of this memory as a native Rust slice, or an error if
502 /// it is out of bounds.
503 ///
504 /// Note that this method will consider the entire store context provided as
505 /// borrowed for the duration of the lifetime of the returned slice.
506 ///
507 /// # Panics
508 ///
509 /// Panics if this memory doesn't belong to `store`.
510 pub fn data_range<'a, T: 'static>(
511 &self,
512 store: impl Into<StoreContext<'a, T>>,
513 range: Range<usize>,
514 ) -> Result<&'a [u8], MemoryAccessError> {
515 self.data(store)
516 .get(range)
517 .ok_or(MemoryAccessError { _private: () })
518 }
519
520 /// Returns `range` of this memory as a native Rust mutable slice, or an
521 /// error if it is out of bounds.
522 ///
523 /// Unlike [`Memory::data_mut`], which hands out all of memory,
524 /// only this range is borrowed for modification, so that Wasmtime
525 /// knows precisely what the host may modify. Prefer this method
526 /// over `data_mut` plus a sub-slice operation: the additional
527 /// semantic information about written memory may be useful to
528 /// Wasmtime for efficiency reasons in some cases.
529 ///
530 /// Note that this method will consider the entire store context provided as
531 /// borrowed for the duration of the lifetime of the returned slice. See
532 /// [`Memory::data_ranges_and_store_data_mut`] to access multiple ranges
533 /// while also borrowing the store's data.
534 ///
535 /// # Panics
536 ///
537 /// Panics if this memory doesn't belong to `store`.
538 pub fn data_range_mut<'a, T: 'static>(
539 &self,
540 store: impl Into<StoreContextMut<'a, T>>,
541 range: Range<usize>,
542 ) -> Result<&'a mut [u8], MemoryAccessError> {
543 let store = store.into();
544 MemoryRanges {
545 memory: *self,
546 store: store.0,
547 }
548 .into_range_mut(range)
549 }
550
551 /// Like [`Memory::data_and_store_mut`], but returns a [`MemoryRanges`]
552 /// through which ranges of memory are read and modified, rather than one
553 /// slice of all of memory, alongside the store's data (the `T` in
554 /// [`Store<T>`](crate::Store)).
555 ///
556 /// This is useful for host code that works with the store's `T` while
557 /// accessing several parts of memory, such as the bindings of a WASI
558 /// implementation: as with [`Memory::data_range_mut`], only the ranges
559 /// borrowed for modification are considered modified.
560 ///
561 /// # Panics
562 ///
563 /// Panics if this memory doesn't belong to `store`.
564 pub fn data_ranges_and_store_data_mut<'a, T: 'static>(
565 &self,
566 store: impl Into<StoreContextMut<'a, T>>,
567 ) -> (MemoryRanges<'a>, &'a mut T) {
568 let store = store.into();
569 assert!(self.comes_from_same_store(store.0));
570 let (data, opaque) = store.0.data_and_opaque_mut();
571 (
572 MemoryRanges {
573 memory: *self,
574 store: opaque,
575 },
576 data,
577 )
578 }
579
580 /// Returns the base pointer, in the host's address space, that the memory
581 /// is located at.
582 ///
583 /// For more information and examples see the documentation on the
584 /// [`Memory`] type.
585 ///
586 /// # Panics
587 ///
588 /// Panics if this memory doesn't belong to `store`.
589 pub fn data_ptr(&self, store: impl AsContext) -> *mut u8 {
590 store.as_context()[self.instance]
591 .memory(self.index)
592 .base
593 .as_ptr()
594 }
595
596 /// Returns the byte length of this memory.
597 ///
598 /// WebAssembly memories are made up of a whole number of pages, so the byte
599 /// size returned will always be a multiple of this memory's page size. Note
600 /// that different Wasm memories may have different page sizes. You can get
601 /// a memory's page size via the [`Memory::page_size`] method.
602 ///
603 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
604 /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
605 /// into a page size of `1`. Future extensions might allow any power of two
606 /// as a page size.
607 ///
608 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
609 ///
610 /// For more information and examples see the documentation on the
611 /// [`Memory`] type.
612 ///
613 /// # Panics
614 ///
615 /// Panics if this memory doesn't belong to `store`.
616 pub fn data_size(&self, store: impl AsContext) -> usize {
617 self.internal_data_size(store.as_context().0)
618 }
619
620 pub(crate) fn internal_data_size(&self, store: &StoreOpaque) -> usize {
621 store[self.instance].memory(self.index).current_length()
622 }
623
624 /// Returns the size, in units of pages, of this Wasm memory.
625 ///
626 /// WebAssembly memories are made up of a whole number of pages, so the byte
627 /// size returned will always be a multiple of this memory's page size. Note
628 /// that different Wasm memories may have different page sizes. You can get
629 /// a memory's page size via the [`Memory::page_size`] method.
630 ///
631 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
632 /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
633 /// into a page size of `1`. Future extensions might allow any power of two
634 /// as a page size.
635 ///
636 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
637 ///
638 /// # Panics
639 ///
640 /// Panics if this memory doesn't belong to `store`.
641 pub fn size(&self, store: impl AsContext) -> u64 {
642 self.internal_size(store.as_context().0)
643 }
644
645 pub(crate) fn internal_size(&self, store: &StoreOpaque) -> u64 {
646 let byte_size = self.internal_data_size(store);
647 let page_size = usize::try_from(self._page_size(store)).unwrap();
648 u64::try_from(byte_size / page_size).unwrap()
649 }
650
651 /// Returns the size of a page, in bytes, for this memory.
652 ///
653 /// WebAssembly memories are made up of a whole number of pages, so the byte
654 /// size (as returned by [`Memory::data_size`]) will always be a multiple of
655 /// their page size. Different Wasm memories may have different page sizes.
656 ///
657 /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
658 /// but [the custom-page-sizes proposal] allows opting into a page size of
659 /// `1`. Future extensions might allow any power of two as a page size.
660 ///
661 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
662 pub fn page_size(&self, store: impl AsContext) -> u64 {
663 self._page_size(store.as_context().0)
664 }
665
666 pub(crate) fn _page_size(&self, store: &StoreOpaque) -> u64 {
667 self.wasmtime_ty(store).page_size()
668 }
669
670 /// Returns the log2 of this memory's page size, in bytes.
671 ///
672 /// WebAssembly memories are made up of a whole number of pages, so the byte
673 /// size (as returned by [`Memory::data_size`]) will always be a multiple of
674 /// their page size. Different Wasm memories may have different page sizes.
675 ///
676 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
677 /// `65536`) but [the custom-page-sizes proposal] allows opting into a page
678 /// size of `1`. Future extensions might allow any power of two as a page
679 /// size.
680 ///
681 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
682 pub fn page_size_log2(&self, store: impl AsContext) -> u8 {
683 self._page_size_log2(store.as_context().0)
684 }
685
686 pub(crate) fn _page_size_log2(&self, store: &StoreOpaque) -> u8 {
687 self.wasmtime_ty(store).page_size_log2
688 }
689
690 /// Grows this WebAssembly memory by `delta` pages.
691 ///
692 /// This will attempt to add `delta` more pages of memory on to the end of
693 /// this `Memory` instance. If successful this may relocate the memory and
694 /// cause [`Memory::data_ptr`] to return a new value. Additionally any
695 /// unsafely constructed slices into this memory may no longer be valid.
696 ///
697 /// On success returns the number of pages this memory previously had
698 /// before the growth succeeded.
699 ///
700 /// Note that, by default, a WebAssembly memory's page size is 64KiB (aka
701 /// 65536 or 2<sup>16</sup>). The [custom-page-sizes proposal] allows Wasm
702 /// memories to opt into a page size of one byte (and this may be further
703 /// relaxed to any power of two in a future extension).
704 ///
705 /// [custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
706 ///
707 /// # Errors
708 ///
709 /// Returns an error if memory could not be grown, for example if it exceeds
710 /// the maximum limits of this memory. A
711 /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
712 /// preventing a memory to grow.
713 ///
714 /// This function will return an error if the [`Store`](`crate::Store`) has
715 /// a [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
716 /// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an
717 /// async resource limiter, use [`Memory::grow_async`] instead.
718 ///
719 /// This function will handle out-of-memory conditions and report an error
720 /// in such cases, see the `OutOfMemory` type's documentation for details on
721 /// Wasmtime's out-of-memory handling. Note that the `OutOfMemory` type may
722 /// not literally be returned for detecting this condition.
723 ///
724 /// # Panics
725 ///
726 /// Panics if this memory doesn't belong to `store`.
727 ///
728 /// # Examples
729 ///
730 /// ```
731 /// # use wasmtime::*;
732 /// # fn main() -> Result<()> {
733 /// let engine = Engine::default();
734 /// let mut store = Store::new(&engine, ());
735 /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1 2))")?;
736 /// let instance = Instance::new(&mut store, &module, &[])?;
737 /// let memory = instance.get_memory(&mut store, "mem").unwrap();
738 ///
739 /// assert_eq!(memory.size(&store), 1);
740 /// assert_eq!(memory.grow(&mut store, 1)?, 1);
741 /// assert_eq!(memory.size(&store), 2);
742 /// assert!(memory.grow(&mut store, 1).is_err());
743 /// assert_eq!(memory.size(&store), 2);
744 /// assert_eq!(memory.grow(&mut store, 0)?, 2);
745 /// # Ok(())
746 /// # }
747 /// ```
748 pub fn grow(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
749 let store = store.as_context_mut().0;
750 let (mut limiter, store) = store.validate_sync_resource_limiter_and_store_opaque()?;
751 vm::assert_ready(self._grow(store, limiter.as_mut(), delta))
752 }
753
754 /// Async variant of [`Memory::grow`]. Required when using a
755 /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
756 ///
757 /// # Panics
758 ///
759 /// This function will panic when used with a non-async
760 /// [`Store`](`crate::Store`).
761 ///
762 /// # Errors
763 ///
764 /// This function will return errors for the same reasons as
765 /// [`Memory::grow`].
766 #[cfg(feature = "async")]
767 pub async fn grow_async(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
768 let store = store.as_context_mut();
769 let (mut limiter, store) = store.0.resource_limiter_and_store_opaque();
770 self._grow(store, limiter.as_mut(), delta).await
771 }
772
773 async fn _grow(
774 &self,
775 store: &mut StoreOpaque,
776 limiter: Option<&mut StoreResourceLimiter<'_>>,
777 delta: u64,
778 ) -> Result<u64> {
779 let result = self
780 .instance
781 .get_mut(store)
782 .memory_grow(limiter, self.index, delta)
783 .await?;
784 match result {
785 Some(size) => {
786 let page_size = self.wasmtime_ty(store).page_size();
787 Ok(u64::try_from(size).unwrap() / page_size)
788 }
789 None => bail!("failed to grow memory by `{delta}`"),
790 }
791 }
792
793 /// Creates a new memory from its raw component parts.
794 ///
795 /// # Safety
796 ///
797 /// The caller must ensure that the memory pointed to by `instance` and
798 /// `index` is not a shared memory. For that `SharedMemory` must be used
799 /// instead.
800 pub(crate) unsafe fn from_raw(instance: StoreInstanceId, index: DefinedMemoryIndex) -> Memory {
801 Memory { instance, index }
802 }
803
804 pub(crate) fn wasmtime_ty<'a>(&self, store: &'a StoreOpaque) -> &'a wasmtime_environ::Memory {
805 let module = store[self.instance].env_module();
806 let index = module.memory_index(self.index);
807 &module.memories[index]
808 }
809
810 pub(crate) fn vmimport(&self, store: &StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
811 store[self.instance].get_defined_memory_vmimport(self.index)
812 }
813
814 pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
815 store.id() == self.instance.store_id()
816 }
817
818 /// This memory's watchpoint shadow, if compiled code checks it.
819 pub(crate) fn vm_shadow<'a>(
820 &self,
821 store: &'a StoreOpaque,
822 ) -> Option<&'a crate::runtime::vm::ShadowMemory> {
823 store[self.instance].get_defined_memory(self.index).shadow()
824 }
825
826 /// This memory's watchpoint shadow, if compiled code checks it.
827 #[cfg(feature = "debug")]
828 pub(crate) fn vm_shadow_mut<'a>(
829 &self,
830 store: &'a mut StoreOpaque,
831 ) -> Option<&'a mut crate::runtime::vm::ShadowMemory> {
832 self.instance
833 .get_mut(store)
834 .get_defined_memory_mut(self.index)
835 .shadow_mut()
836 }
837
838 /// Whether this is the same memory as `other`.
839 #[cfg(feature = "debug")]
840 pub(crate) fn same(&self, other: &Memory) -> bool {
841 self.instance == other.instance && self.index == other.index
842 }
843
844 /// Returns a stable identifier for this memory within its store.
845 ///
846 /// This allows distinguishing memories when introspecting them
847 /// e.g. via debug APIs.
848 #[cfg(feature = "debug")]
849 pub fn debug_index_in_store(&self) -> u64 {
850 u64::from(self.instance.instance().as_u32()) << 32 | u64::from(self.index.as_u32())
851 }
852
853 /// Get a stable hash key for this memory.
854 ///
855 /// Even if the same underlying memory definition is added to the
856 /// `StoreData` multiple times and becomes multiple `wasmtime::Memory`s,
857 /// this hash key will be consistent across all of these memories.
858 #[cfg(feature = "coredump")]
859 pub(crate) fn hash_key(&self, store: &StoreOpaque) -> impl core::hash::Hash + Eq + use<> {
860 store[self.instance].memory_ptr(self.index).as_ptr().addr()
861 }
862}
863
864/// A linear memory. This trait provides an interface for raw memory buffers
865/// which are used by wasmtime, e.g. inside ['Memory']. Such buffers are in
866/// principle not thread safe. By implementing this trait together with
867/// MemoryCreator, one can supply wasmtime with custom allocated host managed
868/// memory.
869///
870/// Note that this is a relatively advanced feature and it is recommended to be
871/// familiar with wasmtime runtime code to use it.
872///
873/// In the following, `minimum`, `reserved_size_in_bytes`, and `guard_size_in_bytes` arguments are given to a
874/// [`MemoryCreator::new_memory`] implementation.
875///
876/// # Safety
877///
878/// Wasmtime's compiled code and runtime rely on the following invariants for memory safety.
879/// Note that while we strive to be thorough in this documentation, we do not guarantee that the
880/// following points are exhaustive.
881/// When using a custom memory backend in a security-sensitive context auditing just the external
882/// implementation of this trait is not sufficient.
883///
884/// - **Valid region.** From creation until the memory is dropped, the first
885/// [`byte_size`] bytes starting at the [`as_ptr`]
886/// memory location must be allocated, initialized, readable, and writeable.
887/// The pointer must be non-null.
888/// Nothing other than Wasmtime may read, write, unmap, or otherwise modify this region while the
889/// memory is in use by Wasmtime.
890/// If the memory moves (although see conditions on stability below), the previous region is no
891/// longer in use by Wasmtime.
892/// Moreover, be aware that Wasmtime currently has a soundness hole for shared memory,
893/// as multiple threads may access the same slice of memory mutably at the same time (aliasing) (see
894/// [issue #4203](https://github.com/bytecodealliance/wasmtime/issues/4203)).
895///
896/// - **Size.** [`byte_size`] must be at least `minimum` after creation
897/// and at least `new_size` after a successful call to [`grow_to`],
898/// and it must never decrease.
899///
900/// - **Base pointer stability.** A call to [`as_ptr`] must return the same
901/// address until the next successful call to [`grow_to`].
902/// Moreover, a successful [`grow_to(new_size)`][`grow_to`] call where `new_size` is at most the [`byte_capacity`](LinearMemory::byte_capacity)
903/// reported before the call must not change the result of [`as_ptr`].
904/// If static memory is forced (e.g. when using shared memory or when [`Config::memory_may_move`](crate::Config::memory_may_move) is disabled), Wasmtime will never ask the memory to grow beyond its [`byte_capacity`].
905///
906/// - **Base pointer alignment.** The base pointer returned by [`as_ptr`] must always be 8-byte aligned.
907/// Moreover, if `guard_size_in_bytes` is non-zero, or `reserved_size_in_bytes` is `Some` and non-zero, then [`as_ptr`] must be
908/// aligned to the host page size at all times.
909///
910/// - **Inaccessible region.** If: `guard_size_in_bytes` is non-zero, or `reserved_size_in_bytes` is `Some` and non-zero;
911/// then every byte from `as_ptr() + byte_size()`, rounded up to the next host page boundary, up to
912/// `as_ptr() + max(reserved_size_in_bytes, byte_size()) + guard_size_in_bytes` must be
913/// inaccessible, so that any access to it faults. This must hold at all times, including after growth.
914///
915/// - **Shared access.** Embedders can obtain `&Self` through [`Memory::linear_memory`] whenever
916/// the owning store is not in use. Methods taking `&self` must therefore be safe to call at any
917/// such time, from any thread, and must not hand out mutable access to state that Wasmtime or
918/// WebAssembly code also mutates, such as the memory's contents.
919///
920/// Additionally, observe the safety requirements when the memory is accessed, as explained in [`Memory`].
921///
922/// # Correctness
923///
924/// The following constraints do not cause memory safety issues, but break WebAssembly semantics,
925/// or expose potentially unwanted data to WebAssembly programs:
926///
927/// - [`byte_size`] should be exactly `minimum` after creation and exactly `new_size` after a
928/// successful call to [`grow_to(new_size)`][`grow_to`]. Wasmtime only requests sizes that are
929/// multiples of the Wasm page size.
930///
931/// - The memory's contents must be zeroed at creation, and bytes made accessible by [`grow_to`] must
932/// be zeroed.
933///
934/// - If [`init_from_image`] returns `Ok(true)`, then the bytes at [`MemoryImage::linear_memory_offset`]
935/// must equal the image and all other bytes must be zero.
936///
937/// [`grow_to`]: LinearMemory::grow_to
938/// [`byte_size`]: LinearMemory::byte_size
939/// [`as_ptr`]: LinearMemory::as_ptr
940/// [`byte_capacity`]: LinearMemory::byte_capacity
941/// [`init_from_image`]: LinearMemory::init_from_image
942pub unsafe trait LinearMemory: Any + Send + Sync {
943 /// Returns the number of allocated bytes which are accessible at this time.
944 fn byte_size(&self) -> usize;
945
946 /// Returns byte capacity of this linear memory's current allocation.
947 ///
948 /// Growth up to this value should not relocate the linear memory base
949 /// pointer.
950 fn byte_capacity(&self) -> usize;
951
952 /// Grows this memory to have the `new_size`, in bytes, specified.
953 ///
954 /// Returns `Err` if memory can't be grown by the specified amount
955 /// of bytes. The error may be downcastable to `std::io::Error`.
956 /// Returns `Ok` if memory was grown successfully.
957 fn grow_to(&mut self, new_size: usize) -> Result<()>;
958
959 /// Return the allocated memory as a mutable pointer to u8.
960 fn as_ptr(&self) -> *mut u8;
961
962 /// Optionally initializes this memory's contents from a copy-on-write
963 /// [`MemoryImage`].
964 ///
965 /// When [copy-on-write memory initialization][cow_config] is enabled and a
966 /// module's data segments for this memory can be represented as an image,
967 /// Wasmtime calls this method once, right after the memory is created
968 /// and before anything else reads or writes it.
969 ///
970 /// If the function succeeds with `false`, the runtime assumes the memory was not initialized.
971 /// It then fully copies the module's data segments into the memory region.
972 /// This is always correct and is essentially equivalent to CoW being disabled.
973 ///
974 /// If the function succeeds with `true`, the runtime assumes the memory's contents match `image` exactly.
975 /// The bytes of the image must start at [`MemoryImage::linear_memory_offset`] and all other bytes must be zero.
976 ///
977 /// ## Shortcut for memory maps
978 ///
979 /// [`MemoryImage`] exposes a shortcut, [`MemoryImage::map_at`], which allows an implementation
980 /// backed by a memory map to replace a portion of its mapping with the pages of the image.
981 /// Consult that function's documentation for safety notes.
982 ///
983 /// Returning an error causes instantiation to fail with that error.
984 ///
985 /// [cow_config]: crate::Config::memory_init_cow
986 fn init_from_image(&mut self, image: &MemoryImage) -> Result<bool> {
987 let _ = image;
988 Ok(false)
989 }
990}
991
992/// A copy-on-write image of the initial contents of a linear memory.
993///
994/// When [`Config::memory_init_cow`](crate::Config::memory_init_cow) is enabled
995/// Wasmtime prepares, where possible, an image of a module's data segments for
996/// each of its linear memories that can be mapped into memory copy-on-write
997/// instead of being copied byte-by-byte. Such images are handed to
998/// [`LinearMemory::init_from_image`] for the specific memory implementation to map into its
999/// underlying representation.
1000///
1001/// An image covers [`len()`](MemoryImage::len) bytes of the linear memory starting at
1002/// [`linear_memory_offset()`](MemoryImage::linear_memory_offset).
1003/// Both values are multiples of the host page size, and the image always lies within
1004/// the minimum size of the memory it was created for.
1005/// All other bytes are expected to be zero.
1006///
1007/// Cloning a `MemoryImage` is cheap and keeps the underlying image alive.
1008#[derive(Clone)]
1009pub struct MemoryImage {
1010 image: Arc<vm::MemoryImage>,
1011}
1012
1013impl MemoryImage {
1014 pub(crate) fn new(image: Arc<vm::MemoryImage>) -> MemoryImage {
1015 MemoryImage { image }
1016 }
1017
1018 /// This is a convenience method for the internal `MmapMemory` to access the underlying image
1019 /// directly and use its [`map_at`](vm::MemoryImage::map_at) function.
1020 #[cfg(has_virtual_memory)]
1021 pub(crate) fn vm(&self) -> &vm::MemoryImage {
1022 &self.image
1023 }
1024
1025 /// Returns the offset, in bytes, within linear memory where this image
1026 /// starts.
1027 ///
1028 /// This is guaranteed to be a multiple of the host page size.
1029 pub fn linear_memory_offset(&self) -> usize {
1030 self.image.linear_memory_offset()
1031 }
1032
1033 /// Returns the length, in bytes, of this image.
1034 ///
1035 /// This is guaranteed to be a multiple of the host page size.
1036 pub fn len(&self) -> usize {
1037 self.image.len()
1038 }
1039
1040 /// Returns whether this image is empty (length equal to zero).
1041 pub fn is_empty(&self) -> bool {
1042 self.len() == 0
1043 }
1044
1045 /// Returns the bytes of this image.
1046 ///
1047 /// The returned slice is [`len()`](MemoryImage::len) bytes long and holds
1048 /// the initial contents of linear memory starting at
1049 /// [`linear_memory_offset()`](MemoryImage::linear_memory_offset). All
1050 /// bytes of the memory outside of that range are initially zero.
1051 pub fn data(&self) -> &[u8] {
1052 self.image.data()
1053 }
1054
1055 /// Maps this image copy-on-write into the linear memory starting at
1056 /// `base`.
1057 ///
1058 /// The bytes `base + linear_memory_offset()` up to
1059 /// `base + linear_memory_offset() + len()` are replaced with a private,
1060 /// readable and writable copy-on-write mapping of the image. Nothing
1061 /// outside of that range is modified.
1062 ///
1063 /// Returns an error if `base` is not aligned to the host page size or if
1064 /// the underlying mapping operation fails.
1065 ///
1066 /// # Safety
1067 ///
1068 /// The caller must exclusively own the virtual memory range being mapped
1069 /// over, nothing may hold references into it, and it must be valid for
1070 /// its pages to be replaced by a new mapping (for example by `mmap` with
1071 /// `MAP_FIXED` on Unix). Any previous contents and memory protections of
1072 /// that range are lost. The mapping lives until the range is unmapped or
1073 /// mapped over again by its owner. In particular, the runtime does not unmap the image by itself.
1074 /// The owner of the virtual memory range must clean it up after usage.
1075 ///
1076 /// The typical usage is owning a memory-mapped region and requesting the image to be mapped
1077 /// into a subrange of that mapping. Unmapping the entire region at the end of the memory's
1078 /// lifetime takes care of the cleanup.
1079 pub unsafe fn map_at(&self, base: *mut u8) -> Result<()> {
1080 // SAFETY: forwarded to the caller.
1081 unsafe { self.image.map_at_ptr(base) }
1082 }
1083}
1084
1085impl fmt::Debug for MemoryImage {
1086 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1087 f.debug_struct("MemoryImage")
1088 .field("linear_memory_offset", &self.linear_memory_offset())
1089 .field("len", &self.len())
1090 .finish_non_exhaustive()
1091 }
1092}
1093
1094impl PartialEq for MemoryImage {
1095 fn eq(&self, other: &Self) -> bool {
1096 Arc::ptr_eq(&self.image, &other.image)
1097 }
1098}
1099
1100impl Eq for MemoryImage {}
1101
1102impl core::hash::Hash for MemoryImage {
1103 fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
1104 core::ptr::hash(Arc::as_ptr(&self.image), state)
1105 }
1106}
1107
1108/// A memory creator. Can be used to provide a memory creator
1109/// to wasmtime which supplies host managed memory.
1110///
1111/// # Safety
1112///
1113/// This trait is unsafe, as the memory safety depends on proper implementation
1114/// of memory management. Memories created by the MemoryCreator should always be
1115/// treated as owned by wasmtime instance, and any modification of them outside
1116/// of wasmtime invoked routines is unsafe and may lead to corruption.
1117///
1118/// Note that this is a relatively advanced feature and it is recommended to be
1119/// familiar with Wasmtime runtime code to use it.
1120pub unsafe trait MemoryCreator: Send + Sync {
1121 /// Create a new [`LinearMemory`] object from the specified parameters.
1122 ///
1123 /// The returned memory must satisfy all of the properties of the [`MemoryRequest`]
1124 /// and be zero filled.
1125 fn new_memory(&self, request: &MemoryRequest<'_>) -> Result<Box<dyn LinearMemory>>;
1126}
1127
1128/// The kind of memory that [`MemoryCreator`] is asked to create.
1129#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
1130#[non_exhaustive]
1131pub enum MemoryKind {
1132 /// A standard WebAssembly linear memory (module or host).
1133 LinearMemory,
1134 /// The memory backing a store's GC heap.
1135 ///
1136 /// It differs from standard linear memory:
1137 /// - It is created lazily, at most once per store: when a module that needs a GC heap is
1138 /// instantiated or when the first GC object is allocated. This might happen in the middle of
1139 /// execution of WebAssembly code.
1140 /// - It grows as GC objects are allocated, independently of `memory.grow`.
1141 /// - Its contents are Wasmtime's internal representation of GC objects, not data of the guest
1142 /// program. They are only meaningful to the store that created the GC heap, so they should not
1143 /// be shared, persisted, copied to other memories, etc.
1144 GcHeap,
1145}
1146
1147impl From<wasmtime_environ::MemoryKind> for MemoryKind {
1148 fn from(value: wasmtime_environ::MemoryKind) -> Self {
1149 match value {
1150 wasmtime_environ::MemoryKind::LinearMemory => Self::LinearMemory,
1151 wasmtime_environ::MemoryKind::GcHeap => Self::GcHeap,
1152 }
1153 }
1154}
1155
1156/// A request to a [`MemoryCreator::new_memory`].
1157pub struct MemoryRequest<'a> {
1158 ty: &'a wasmtime_environ::Memory,
1159 tunables: &'a MemoryTunables<'a>,
1160 minimum: usize,
1161 maximum: Option<usize>,
1162}
1163
1164impl<'a> MemoryRequest<'a> {
1165 pub(crate) fn new(
1166 ty: &'a wasmtime_environ::Memory,
1167 tunables: &'a MemoryTunables<'a>,
1168 minimum: usize,
1169 maximum: Option<usize>,
1170 ) -> Self {
1171 Self {
1172 ty,
1173 tunables,
1174 minimum,
1175 maximum,
1176 }
1177 }
1178
1179 /// The type of memory being created. Indicates
1180 /// both the minimum and maximum size, in wasm pages. The minimum and
1181 /// maximum sizes, in bytes, are also specified as [`minimum`](Self::minimum) and [`maximum`](Self::maximum)
1182 /// to avoid integer conversion if desired.
1183 pub fn ty(&self) -> MemoryType {
1184 MemoryType::from_wasmtime_memory(self.ty)
1185 }
1186
1187 /// Minimum size of the memory in bytes.
1188 /// Same as the minimum of [`ty`](Self::ty), but in bytes.
1189 pub fn minimum(&self) -> usize {
1190 self.minimum
1191 }
1192
1193 /// Limit on the maximum size of the memory in bytes, if any.
1194 /// Same as the maximum of [`ty`](Self::ty), but in bytes.
1195 pub fn maximum(&self) -> Option<usize> {
1196 self.maximum
1197 }
1198
1199 /// Indicates the expected size of the reservation that is to be made for this memory.
1200 /// The implementation must reserve this many bytes for the memory's allocation, plus the guard
1201 /// size at the end. Note that this reservation need only be a virtual
1202 /// memory reservation, physical memory does not need to be allocated
1203 /// immediately.
1204 ///
1205 /// If this value is not zero, [`grow_to`](LinearMemory::grow_to) should never move the base pointer and
1206 /// the maximum size of [`ty`](Self::ty) is guaranteed to fit within `reserved_size_in_bytes`.
1207 ///
1208 /// This value is tuned from the various [`Config`](crate::Config) methods about
1209 /// memory sizes/guards. It is guaranteed to be a multiple of the system page size.
1210 pub fn reserved_size_in_bytes(&self) -> usize {
1211 usize::try_from(self.tunables.reservation()).unwrap()
1212 }
1213
1214 /// Indicates how many bytes of space after the memory allocation is expected to be unmapped. JIT code will
1215 /// elide bounds checks based on the `guard_size_in_bytes` provided, so for
1216 /// JIT code to work correctly the memory returned will need to be properly
1217 /// guarded with `guard_size_in_bytes` bytes left unmapped after the base
1218 /// allocation.
1219 ///
1220 /// This value is tuned from the various [`Config`](crate::Config) methods about
1221 /// memory sizes/guards. It is guaranteed to be a multiple of the system page size.
1222 pub fn guard_size_in_bytes(&self) -> usize {
1223 usize::try_from(self.tunables.guard_size()).unwrap()
1224 }
1225
1226 /// What kind of memory is requested.
1227 pub fn kind(&self) -> MemoryKind {
1228 self.tunables.kind().into()
1229 }
1230
1231 /// Internal parameter: detailed internal representation of the memory being created.
1232 pub(crate) fn wasmtime_memory(&self) -> &'a wasmtime_environ::Memory {
1233 self.ty
1234 }
1235
1236 /// Internal parameter: all the tunables, including those not exposed to the public API.
1237 pub(crate) fn tunables(&self) -> &'a MemoryTunables<'a> {
1238 self.tunables
1239 }
1240}
1241
1242impl fmt::Debug for MemoryRequest<'_> {
1243 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1244 f.debug_struct("MemoryRequest")
1245 .field("ty", &self.ty())
1246 .field("minimum", &self.minimum)
1247 .field("maximum", &self.maximum)
1248 .field("reserved_size_in_bytes", &self.reserved_size_in_bytes())
1249 .field("guard_size_in_bytes", &self.guard_size_in_bytes())
1250 .field("kind", &self.kind())
1251 .finish()
1252 }
1253}
1254
1255/// A constructor for externally-created shared memory.
1256///
1257/// The [threads proposal] adds the concept of "shared memory" to WebAssembly.
1258/// This is much the same as a Wasm linear memory (i.e., [`Memory`]), but can be
1259/// used concurrently by multiple agents. Because these agents may execute in
1260/// different threads, [`SharedMemory`] must be thread-safe.
1261///
1262/// When the [threads proposal is enabled](crate::Config::wasm_threads) and the
1263/// [the creation of shared memories is enabled](crate::Config::shared_memory),
1264/// there are multiple ways to construct shared memory:
1265/// 1. for imported shared memory, e.g., `(import "env" "memory" (memory 1 1
1266/// shared))`, the user must supply a [`SharedMemory`] with the
1267/// externally-created memory as an import to the instance--e.g.,
1268/// `shared_memory.into()`.
1269/// 2. for private or exported shared memory, e.g., `(export "env" "memory"
1270/// (memory 1 1 shared))`, Wasmtime will create the memory internally during
1271/// instantiation--access using `Instance::get_shared_memory()`.
1272///
1273/// [threads proposal]:
1274/// https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md
1275///
1276/// # Examples
1277///
1278/// ```
1279/// # use wasmtime::*;
1280/// # fn main() -> Result<()> {
1281/// let mut config = Config::new();
1282/// config.wasm_threads(true);
1283/// config.shared_memory(true);
1284/// # if Engine::new(&config).is_err() { return Ok(()); }
1285/// let engine = Engine::new(&config)?;
1286/// let mut store = Store::new(&engine, ());
1287///
1288/// let shared_memory = SharedMemory::new(&engine, MemoryType::shared(1, 2)?)?;
1289/// let module = Module::new(&engine, r#"(module (memory (import "" "") 1 2 shared))"#)?;
1290/// let instance = Instance::new(&mut store, &module, &[shared_memory.into()])?;
1291/// // ...
1292/// # Ok(())
1293/// # }
1294/// ```
1295#[derive(Clone)]
1296pub struct SharedMemory {
1297 vm: crate::runtime::vm::SharedMemory,
1298 engine: Engine,
1299}
1300
1301impl SharedMemory {
1302 /// Construct a [`SharedMemory`] by providing both the `minimum` and
1303 /// `maximum` number of 64K-sized pages. This call allocates the necessary
1304 /// pages on the system.
1305 ///
1306 /// # Errors
1307 ///
1308 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
1309 /// memory allocation fails. See the `OutOfMemory` type's documentation for
1310 /// details on Wasmtime's out-of-memory handling.
1311 #[cfg(feature = "threads")]
1312 pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self> {
1313 if !ty.is_shared() {
1314 bail!("shared memory must have the `shared` flag enabled on its memory type")
1315 }
1316 debug_assert!(ty.maximum().is_some());
1317
1318 let ty = ty.wasmtime_memory();
1319 let memory = crate::runtime::vm::SharedMemory::new(engine, ty)?;
1320
1321 Ok(Self {
1322 vm: memory,
1323 engine: engine.clone(),
1324 })
1325 }
1326
1327 /// Return the type of the shared memory.
1328 pub fn ty(&self) -> MemoryType {
1329 MemoryType::from_wasmtime_memory(&self.vm.ty())
1330 }
1331
1332 /// Returns the size, in WebAssembly pages, of this wasm memory.
1333 pub fn size(&self) -> u64 {
1334 let byte_size = u64::try_from(self.data_size()).unwrap();
1335 let page_size = self.page_size();
1336 byte_size / page_size
1337 }
1338
1339 /// Returns the size of a page, in bytes, for this memory.
1340 ///
1341 /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
1342 /// but [the custom-page-sizes proposal] allows opting into a page size of
1343 /// `1`. Future extensions might allow any power of two as a page size.
1344 ///
1345 /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
1346 pub fn page_size(&self) -> u64 {
1347 self.ty().page_size()
1348 }
1349
1350 /// Returns the byte length of this memory.
1351 ///
1352 /// The returned value will be a multiple of the wasm page size, 64k.
1353 ///
1354 /// For more information and examples see the documentation on the
1355 /// [`Memory`] type.
1356 pub fn data_size(&self) -> usize {
1357 self.vm.byte_size()
1358 }
1359
1360 /// Return access to the available portion of the shared memory.
1361 ///
1362 /// The slice returned represents the region of accessible memory at the
1363 /// time that this function was called. The contents of the returned slice
1364 /// will reflect concurrent modifications happening on other threads.
1365 ///
1366 /// # Safety
1367 ///
1368 /// The returned slice is valid for the entire duration of the lifetime of
1369 /// this instance of [`SharedMemory`]. The base pointer of a shared memory
1370 /// does not change. This [`SharedMemory`] may grow further after this
1371 /// function has been called, but the slice returned will not grow.
1372 ///
1373 /// Concurrent modifications may be happening to the data returned on other
1374 /// threads. The `UnsafeCell<u8>` represents that safe access to the
1375 /// contents of the slice is not possible through normal loads and stores.
1376 ///
1377 /// The memory returned must be accessed safely through the `Atomic*` types
1378 /// in the [`std::sync::atomic`] module. Casting to those types must
1379 /// currently be done unsafely.
1380 pub fn data(&self) -> &[UnsafeCell<u8>] {
1381 unsafe {
1382 let definition = self.vm.vmmemory_ptr().as_ref();
1383 slice::from_raw_parts(definition.base.as_ptr().cast(), definition.current_length())
1384 }
1385 }
1386
1387 /// Grows this WebAssembly memory by `delta` pages.
1388 ///
1389 /// This will attempt to add `delta` more pages of memory on to the end of
1390 /// this `Memory` instance. If successful this may relocate the memory and
1391 /// cause [`Memory::data_ptr`] to return a new value. Additionally any
1392 /// unsafely constructed slices into this memory may no longer be valid.
1393 ///
1394 /// On success returns the number of pages this memory previously had
1395 /// before the growth succeeded.
1396 ///
1397 /// # Errors
1398 ///
1399 /// This function will return errors for a similar reason as
1400 /// [`Memory::grow`].
1401 pub fn grow(&self, delta: u64) -> Result<u64> {
1402 match self.vm.grow(delta)? {
1403 Some((old_size, _new_size)) => {
1404 // For shared memory, the `VMMemoryDefinition` is updated inside
1405 // the locked region.
1406 Ok(u64::try_from(old_size).unwrap() / self.page_size())
1407 }
1408 None => bail!("failed to grow memory by `{delta}`"),
1409 }
1410 }
1411
1412 /// Returns a stable identifier for this shared memory when introspecting
1413 /// it through the debug APIs.
1414 #[cfg(feature = "debug")]
1415 pub fn debug_index_in_store(&self) -> u64 {
1416 u64::try_from(self.vm.vmmemory_ptr().as_ptr().addr()).unwrap()
1417 }
1418
1419 /// Equivalent of the WebAssembly `memory.atomic.notify` instruction for
1420 /// this shared memory.
1421 ///
1422 /// This method allows embedders to notify threads blocked on the specified
1423 /// `addr`, an index into wasm linear memory. Threads could include
1424 /// wasm threads blocked on a `memory.atomic.wait*` instruction or embedder
1425 /// threads blocked on [`SharedMemory::atomic_wait32`], for example.
1426 ///
1427 /// The `count` argument is the number of threads to wake up.
1428 ///
1429 /// This function returns the number of threads awoken.
1430 ///
1431 /// # Errors
1432 ///
1433 /// This function will return an error if `addr` is not within bounds or
1434 /// not aligned to a 4-byte boundary.
1435 pub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap> {
1436 self.vm.atomic_notify(addr, count)
1437 }
1438
1439 /// Equivalent of the WebAssembly `memory.atomic.wait32` instruction for
1440 /// this shared memory.
1441 ///
1442 /// This method allows embedders to block the current thread until notified
1443 /// via the `memory.atomic.notify` instruction or the
1444 /// [`SharedMemory::atomic_notify`] method, enabling synchronization with
1445 /// the wasm guest as desired.
1446 ///
1447 /// The `expected` argument is the expected 32-bit value to be stored at
1448 /// the byte address `addr` specified. The `addr` specified is an index
1449 /// into this linear memory.
1450 ///
1451 /// The optional `timeout` argument is the maximum amount of time to block
1452 /// the current thread. If not specified the thread may sleep indefinitely.
1453 ///
1454 /// This function returns one of three possible values:
1455 ///
1456 /// * `WaitResult::Ok` - this function, loaded the value at `addr`, found
1457 /// it was equal to `expected`, and then blocked (all as one atomic
1458 /// operation). The thread was then awoken with a `memory.atomic.notify`
1459 /// instruction or the [`SharedMemory::atomic_notify`] method.
1460 /// * `WaitResult::Mismatch` - the value at `addr` was loaded but was not
1461 /// equal to `expected` so the thread did not block and immediately
1462 /// returned.
1463 /// * `WaitResult::TimedOut` - all the steps of `Ok` happened, except this
1464 /// thread was woken up due to a timeout.
1465 ///
1466 /// This function will not return due to spurious wakeups.
1467 ///
1468 /// # Errors
1469 ///
1470 /// This function will return an error if `addr` is not within bounds or
1471 /// not aligned to a 4-byte boundary.
1472 pub fn atomic_wait32(
1473 &self,
1474 addr: u64,
1475 expected: u32,
1476 timeout: Option<Duration>,
1477 ) -> Result<WaitResult, Trap> {
1478 self.vm.atomic_wait32(addr, expected, timeout)
1479 }
1480
1481 /// Equivalent of the WebAssembly `memory.atomic.wait64` instruction for
1482 /// this shared memory.
1483 ///
1484 /// For more information see [`SharedMemory::atomic_wait32`].
1485 ///
1486 /// # Errors
1487 ///
1488 /// Returns the same error as [`SharedMemory::atomic_wait32`] except that
1489 /// the specified address must be 8-byte aligned instead of 4-byte aligned.
1490 pub fn atomic_wait64(
1491 &self,
1492 addr: u64,
1493 expected: u64,
1494 timeout: Option<Duration>,
1495 ) -> Result<WaitResult, Trap> {
1496 self.vm.atomic_wait64(addr, expected, timeout)
1497 }
1498
1499 /// Return a reference to the [`Engine`] used to configure the shared
1500 /// memory.
1501 pub(crate) fn engine(&self) -> &Engine {
1502 &self.engine
1503 }
1504
1505 /// Construct a single-memory instance to provide a way to import
1506 /// [`SharedMemory`] into other modules.
1507 pub(crate) fn vmimport(&self, store: &mut StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
1508 // Note `vm::assert_ready` shouldn't panic here because this isn't
1509 // actually allocating any new memory (also no limiter), so resource
1510 // limiting shouldn't kick in.
1511 let memory = vm::assert_ready(generate_memory_export(
1512 store,
1513 None,
1514 &self.ty(),
1515 Some(&self.vm),
1516 ))
1517 .unwrap();
1518 match memory {
1519 ExportMemory::Unshared(_) => unreachable!(),
1520 ExportMemory::Shared(_shared, vmimport) => vmimport,
1521 }
1522 }
1523
1524 /// Creates a [`SharedMemory`] from its constituent parts.
1525 pub(crate) fn from_raw(vm: crate::runtime::vm::SharedMemory, engine: Engine) -> Self {
1526 SharedMemory { vm, engine }
1527 }
1528}
1529
1530impl fmt::Debug for SharedMemory {
1531 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1532 f.debug_struct("SharedMemory").finish_non_exhaustive()
1533 }
1534}
1535
1536#[cfg(test)]
1537mod tests {
1538 use crate::*;
1539
1540 // Assert that creating a memory via `Memory::new` respects the limits/tunables
1541 // in `Config`.
1542 #[test]
1543 fn respect_tunables() {
1544 let mut cfg = Config::new();
1545 cfg.memory_reservation(0).memory_guard_size(0);
1546 let mut store = Store::new(&Engine::new(&cfg).unwrap(), ());
1547 let ty = MemoryType::new(1, None).unwrap();
1548 let mem = Memory::new(&mut store, ty).unwrap();
1549 let store = store.as_context();
1550 let tunables = store.engine().tunables();
1551 assert_eq!(tunables.memory_guard_size, 0);
1552 assert!(!mem.wasmtime_ty(store.0).can_elide_bounds_check(
1553 &wasmtime_environ::MemoryTunables::new(
1554 tunables,
1555 wasmtime_environ::MemoryKind::LinearMemory,
1556 ),
1557 12,
1558 ));
1559 }
1560
1561 #[test]
1562 fn hash_key_is_stable_across_duplicate_store_data_entries() -> Result<()> {
1563 let mut store = Store::<()>::default();
1564 let module = Module::new(
1565 store.engine(),
1566 r#"
1567 (module
1568 (memory (export "m") 1 1)
1569 )
1570 "#,
1571 )?;
1572 let instance = Instance::new(&mut store, &module, &[])?;
1573
1574 // Each time we `get_memory`, we call `Memory::from_wasmtime` which adds
1575 // a new entry to `StoreData`, so `g1` and `g2` will have different
1576 // indices into `StoreData`.
1577 let m1 = instance.get_memory(&mut store, "m").unwrap();
1578 let m2 = instance.get_memory(&mut store, "m").unwrap();
1579
1580 // That said, they really point to the same memory.
1581 assert_eq!(m1.data(&store)[0], 0);
1582 assert_eq!(m2.data(&store)[0], 0);
1583 m1.data_mut(&mut store)[0] = 42;
1584 assert_eq!(m1.data(&mut store)[0], 42);
1585 assert_eq!(m2.data(&mut store)[0], 42);
1586
1587 // And therefore their hash keys are the same.
1588 assert!(m1.hash_key(&store.as_context().0) == m2.hash_key(&store.as_context().0));
1589
1590 // But the hash keys are different from different memories.
1591 let instance2 = Instance::new(&mut store, &module, &[])?;
1592 let m3 = instance2.get_memory(&mut store, "m").unwrap();
1593 assert!(m1.hash_key(&store.as_context().0) != m3.hash_key(&store.as_context().0));
1594
1595 Ok(())
1596 }
1597
1598 /// Offset of the data segment used by the `MemoryImage` tests: inside the
1599 /// second Wasm page, but not at the start of a host page.
1600 #[cfg(all(target_os = "linux", not(miri)))]
1601 const IMAGE_DATA_OFFSET: usize = 0x10000 + 8;
1602
1603 /// Compiles a module whose single memory is initialized by one data segment
1604 /// at `IMAGE_DATA_OFFSET` and returns the CoW image Wasmtime builds for it.
1605 /// The module is never instantiated, we just take the image of the memory.
1606 #[cfg(all(target_os = "linux", not(miri)))]
1607 fn memory_image_for_data(data: &str) -> Result<MemoryImage> {
1608 let mut config = Config::new();
1609 config.memory_init_cow(true);
1610 let engine = Engine::new(&config)?;
1611 let module = Module::new(
1612 &engine,
1613 // Module with (at least) 2 pages of memory with data written at IMAGE_DATA_OFFSET.
1614 format!("(module (memory 2) (data (i32.const {IMAGE_DATA_OFFSET}) \"{data}\"))"),
1615 )?;
1616 let images = module.memory_images()?.expect("module has memory images");
1617 let image = images
1618 .get_memory_image(wasmtime_environ::DefinedMemoryIndex::from_u32(0))
1619 .expect("memory 0 has an image");
1620 Ok(MemoryImage::new(image.clone()))
1621 }
1622
1623 /// The public accessors report the internal image's placement, and:
1624 /// - both values are multiples of the host page size; and
1625 /// - the image covers the module's data.
1626 #[test]
1627 #[cfg(all(target_os = "linux", not(miri)))]
1628 fn memory_image_accessors() -> Result<()> {
1629 let page_size = crate::runtime::vm::host_page_size();
1630 let image = memory_image_for_data("hello")?;
1631 let offset = image.linear_memory_offset();
1632 let len = image.len();
1633
1634 assert_eq!(offset, image.vm().linear_memory_offset());
1635 assert_eq!(len, image.vm().len());
1636 assert_eq!(offset % page_size, 0);
1637 assert_eq!(len % page_size, 0);
1638 assert!(!image.is_empty());
1639 // Image starts at or before the data...
1640 assert!(offset <= IMAGE_DATA_OFFSET);
1641 // ... and reaches past the end of the data.
1642 assert!(offset + len >= IMAGE_DATA_OFFSET + "hello".len());
1643
1644 let data = image.data();
1645 assert_eq!(data.len(), len);
1646 assert_eq!(data, image.vm().data());
1647 let data_start = IMAGE_DATA_OFFSET - offset;
1648 assert_eq!(&data[data_start..][..5], b"hello");
1649 assert!(data[..data_start].iter().all(|b| *b == 0));
1650 assert!(data[data_start + 5..].iter().all(|b| *b == 0));
1651
1652 // Clones share the same underlying image.
1653 let clone = image.clone();
1654 assert!(core::ptr::eq(clone.vm(), image.vm()));
1655 Ok(())
1656 }
1657
1658 #[test]
1659 #[cfg(all(target_os = "linux", not(miri)))]
1660 fn memory_image_identity() -> Result<()> {
1661 use std::hash::{BuildHasher, RandomState};
1662
1663 let mut config = Config::new();
1664 config.memory_init_cow(true);
1665 let engine = Engine::new(&config)?;
1666 let wat = r#"(module (memory 1) (data (i32.const 0) "hello"))"#;
1667 let image_of = |module: &Module| -> Result<MemoryImage> {
1668 let images = module.memory_images()?.expect("module has memory images");
1669 let image = images
1670 .get_memory_image(wasmtime_environ::DefinedMemoryIndex::from_u32(0))
1671 .expect("memory 0 has an image");
1672 Ok(MemoryImage::new(image.clone()))
1673 };
1674
1675 let module = Module::new(&engine, wat)?;
1676 let image = image_of(&module)?;
1677 let same = image_of(&module)?; // Same module instance gives the same image.
1678 let clone = image.clone(); // Clone just clones an Arc.
1679
1680 assert_eq!(image, same);
1681 assert_eq!(image, clone);
1682
1683 let hasher = RandomState::new();
1684 assert_eq!(hasher.hash_one(&image), hasher.hash_one(&same));
1685 assert_eq!(hasher.hash_one(&image), hasher.hash_one(&clone));
1686
1687 Ok(())
1688 }
1689
1690 /// `MemoryImage::map_at` places the image's bytes at
1691 /// `base + linear_memory_offset()` and zeroes the rest.
1692 #[test]
1693 #[cfg(all(target_os = "linux", not(miri)))]
1694 fn memory_image_map_at() -> Result<()> {
1695 use crate::runtime::vm::{HostAlignedByteCount, Mmap};
1696
1697 let image = memory_image_for_data("hello")?;
1698 let size =
1699 HostAlignedByteCount::new_rounded_up(image.linear_memory_offset() + image.len())?;
1700 let mmap = Mmap::accessible_reserved(HostAlignedByteCount::ZERO, size)?;
1701 let base = mmap.as_non_null().as_ptr();
1702
1703 // SAFETY: `mmap` was just created, is owned by this test and covers
1704 // the whole range the image is mapped into.
1705 unsafe { image.map_at(base)? };
1706
1707 // SAFETY: `map_at` made the image's range readable.
1708 let mapped = unsafe {
1709 core::slice::from_raw_parts(base.add(image.linear_memory_offset()), image.len())
1710 };
1711 let data_start = IMAGE_DATA_OFFSET - image.linear_memory_offset();
1712
1713 assert_eq!(mapped, image.data());
1714 assert_eq!(&mapped[data_start..][..5], b"hello");
1715 assert!(mapped[..data_start].iter().all(|b| *b == 0));
1716 assert!(mapped[data_start + 5..].iter().all(|b| *b == 0));
1717
1718 Ok(())
1719 }
1720}
1721
1722/// Access to ranges of a [`Memory`], from
1723/// [`Memory::data_ranges_and_store_data_mut`].
1724///
1725/// Ranges are read with [`MemoryRanges::data_range`] (or all of memory with
1726/// [`MemoryRanges::data`]) and modified with
1727/// [`MemoryRanges::data_range_mut`], which considers only the range it
1728/// returns modified.
1729pub struct MemoryRanges<'a> {
1730 memory: Memory,
1731 store: &'a mut StoreOpaque,
1732}
1733
1734impl<'a> MemoryRanges<'a> {
1735 /// The length of the memory, in bytes.
1736 pub fn len(&self) -> usize {
1737 self.memory.internal_data_size(self.store)
1738 }
1739
1740 /// Whether the memory is empty.
1741 pub fn is_empty(&self) -> bool {
1742 self.len() == 0
1743 }
1744
1745 /// All of the memory, for reading.
1746 pub fn data(&self) -> &[u8] {
1747 let definition = self.store[self.memory.instance].memory(self.memory.index);
1748 // SAFETY: the store owns this non-shared memory, and this borrow of
1749 // `self` excludes modification through it.
1750 unsafe { slice::from_raw_parts(definition.base.as_ptr(), definition.current_length()) }
1751 }
1752
1753 /// `range` of the memory, for reading, or an error if it is out of
1754 /// bounds.
1755 pub fn data_range(&self, range: Range<usize>) -> Result<&[u8], MemoryAccessError> {
1756 self.data()
1757 .get(range)
1758 .ok_or(MemoryAccessError { _private: () })
1759 }
1760
1761 /// `range` of the memory, for modification, or an error if it is out of
1762 /// bounds. Only this range is considered modified.
1763 pub fn data_range_mut(&mut self, range: Range<usize>) -> Result<&mut [u8], MemoryAccessError> {
1764 MemoryRanges {
1765 memory: self.memory,
1766 store: &mut *self.store,
1767 }
1768 .into_range_mut(range)
1769 }
1770
1771 fn into_range_mut(self, range: Range<usize>) -> Result<&'a mut [u8], MemoryAccessError> {
1772 let len = self.len();
1773 if range.start > range.end || range.end > len {
1774 return Err(MemoryAccessError { _private: () });
1775 }
1776 let definition = self.store[self.memory.instance].memory(self.memory.index);
1777 // SAFETY: the range is in bounds, and the store, which owns this
1778 // non-shared memory, is borrowed for the slice's lifetime.
1779 unsafe {
1780 Ok(slice::from_raw_parts_mut(
1781 definition.base.as_ptr().add(range.start),
1782 range.len(),
1783 ))
1784 }
1785 }
1786}