Skip to main content

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}