wasmtime/runtime/
memory.rs

1use crate::Trap;
2use crate::prelude::*;
3use crate::runtime::vm::VMMemoryImport;
4use crate::store::{StoreInstanceId, StoreOpaque};
5use crate::trampoline::generate_memory_export;
6use crate::{AsContext, AsContextMut, Engine, MemoryType, StoreContext, StoreContextMut};
7use core::cell::UnsafeCell;
8use core::fmt;
9use core::slice;
10use core::time::Duration;
11use wasmtime_environ::DefinedMemoryIndex;
12
13pub use crate::runtime::vm::WaitResult;
14
15/// Error for out of bounds [`Memory`] access.
16#[derive(Debug)]
17#[non_exhaustive]
18pub struct MemoryAccessError {
19    // Keep struct internals private for future extensibility.
20    _private: (),
21}
22
23impl fmt::Display for MemoryAccessError {
24    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
25        write!(f, "out of bounds memory access")
26    }
27}
28
29#[cfg(feature = "std")]
30impl std::error::Error for MemoryAccessError {}
31
32/// A WebAssembly linear memory.
33///
34/// WebAssembly memories represent a contiguous array of bytes that have a size
35/// that is always a multiple of the WebAssembly page size, currently 64
36/// kilobytes.
37///
38/// WebAssembly memory is used for global data (not to be confused with wasm
39/// `global` items), statics in C/C++/Rust, shadow stack memory, etc. Accessing
40/// wasm memory is generally quite fast.
41///
42/// Memories, like other wasm items, are owned by a [`Store`](crate::Store).
43///
44/// # `Memory` and Safety
45///
46/// Linear memory is a lynchpin of safety for WebAssembly. In Wasmtime there are
47/// safe methods of interacting with a [`Memory`]:
48///
49/// * [`Memory::read`]
50/// * [`Memory::write`]
51/// * [`Memory::data`]
52/// * [`Memory::data_mut`]
53///
54/// Note that all of these consider the entire store context as borrowed for the
55/// duration of the call or the duration of the returned slice. This largely
56/// means that while the function is running you'll be unable to borrow anything
57/// else from the store. This includes getting access to the `T` on
58/// [`Store<T>`](crate::Store), but it also means that you can't recursively
59/// call into WebAssembly for instance.
60///
61/// If you'd like to dip your toes into handling [`Memory`] in a more raw
62/// fashion (e.g. by using raw pointers or raw slices), then there's a few
63/// important points to consider when doing so:
64///
65/// * Any recursive calls into WebAssembly can possibly modify any byte of the
66///   entire memory. This means that whenever wasm is called Rust can't have any
67///   long-lived borrows live across the wasm function call. Slices like `&mut
68///   [u8]` will be violated because they're not actually exclusive at that
69///   point, and slices like `&[u8]` are also violated because their contents
70///   may be mutated.
71///
72/// * WebAssembly memories can grow, and growth may change the base pointer.
73///   This means that even holding a raw pointer to memory over a wasm function
74///   call is also incorrect. Anywhere in the function call the base address of
75///   memory may change. Note that growth can also be requested from the
76///   embedding API as well.
77///
78/// As a general rule of thumb it's recommended to stick to the safe methods of
79/// [`Memory`] if you can. It's not advised to use raw pointers or `unsafe`
80/// operations because of how easy it is to accidentally get things wrong.
81///
82/// Some examples of safely interacting with memory are:
83///
84/// ```rust
85/// use wasmtime::{Memory, Store, MemoryAccessError};
86///
87/// // Memory can be read and written safely with the `Memory::read` and
88/// // `Memory::write` methods.
89/// // An error is returned if the copy did not succeed.
90/// fn safe_examples(mem: Memory, store: &mut Store<()>) -> Result<(), MemoryAccessError> {
91///     let offset = 5;
92///     mem.write(&mut *store, offset, b"hello")?;
93///     let mut buffer = [0u8; 5];
94///     mem.read(&store, offset, &mut buffer)?;
95///     assert_eq!(b"hello", &buffer);
96///
97///     // Note that while this is safe care must be taken because the indexing
98///     // here may panic if the memory isn't large enough.
99///     assert_eq!(&mem.data(&store)[offset..offset + 5], b"hello");
100///     mem.data_mut(&mut *store)[offset..offset + 5].copy_from_slice(b"bye!!");
101///
102///     Ok(())
103/// }
104/// ```
105///
106/// It's worth also, however, covering some examples of **incorrect**,
107/// **unsafe** usages of `Memory`. Do not do these things!
108///
109/// ```rust
110/// # use anyhow::Result;
111/// use wasmtime::{Memory, Store};
112///
113/// // NOTE: All code in this function is not safe to execute and may cause
114/// // segfaults/undefined behavior at runtime. Do not copy/paste these examples
115/// // into production code!
116/// unsafe fn unsafe_examples(mem: Memory, store: &mut Store<()>) -> Result<()> {
117///     // First and foremost, any borrow can be invalidated at any time via the
118///     // `Memory::grow` function. This can relocate memory which causes any
119///     // previous pointer to be possibly invalid now.
120///     unsafe {
121///         let pointer: &u8 = &*mem.data_ptr(&store);
122///         mem.grow(&mut *store, 1)?; // invalidates `pointer`!
123///         // println!("{}", *pointer); // FATAL: use-after-free
124///     }
125///
126///     // Note that the use-after-free also applies to slices, whether they're
127///     // slices of bytes or strings.
128///     unsafe {
129///         let mem_slice = std::slice::from_raw_parts(
130///             mem.data_ptr(&store),
131///             mem.data_size(&store),
132///         );
133///         let slice: &[u8] = &mem_slice[0x100..0x102];
134///         mem.grow(&mut *store, 1)?; // invalidates `slice`!
135///         // println!("{:?}", slice); // FATAL: use-after-free
136///     }
137///
138///     // The `Memory` type may be stored in other locations, so if you hand
139///     // off access to the `Store` then those locations may also call
140///     // `Memory::grow` or similar, so it's not enough to just audit code for
141///     // calls to `Memory::grow`.
142///     unsafe {
143///         let pointer: &u8 = &*mem.data_ptr(&store);
144///         some_other_function(store); // may invalidate `pointer` through use of `store`
145///         // println!("{:?}", pointer); // FATAL: maybe a use-after-free
146///     }
147///
148///     // An especially subtle aspect of accessing a wasm instance's memory is
149///     // that you need to be extremely careful about aliasing. Anyone at any
150///     // time can call `data_unchecked()` or `data_unchecked_mut()`, which
151///     // means you can easily have aliasing mutable references:
152///     unsafe {
153///         let ref1: &u8 = &*mem.data_ptr(&store).add(0x100);
154///         let ref2: &mut u8 = &mut *mem.data_ptr(&store).add(0x100);
155///         // *ref2 = *ref1; // FATAL: violates Rust's aliasing rules
156///     }
157///
158///     Ok(())
159/// }
160/// # fn some_other_function(store: &mut Store<()>) {}
161/// ```
162///
163/// Overall there's some general rules of thumb when unsafely working with
164/// `Memory` and getting raw pointers inside of it:
165///
166/// * If you never have a "long lived" pointer into memory, you're likely in the
167///   clear. Care still needs to be taken in threaded scenarios or when/where
168///   data is read, but you'll be shielded from many classes of issues.
169/// * Long-lived pointers must always respect Rust'a aliasing rules. It's ok for
170///   shared borrows to overlap with each other, but mutable borrows must
171///   overlap with nothing.
172/// * Long-lived pointers are only valid if they're not invalidated for their
173///   lifetime. This means that [`Store`](crate::Store) isn't used to reenter
174///   wasm or the memory itself is never grown or otherwise modified/aliased.
175///
176/// At this point it's worth reiterating again that unsafely working with
177/// `Memory` is pretty tricky and not recommended! It's highly recommended to
178/// use the safe methods to interact with [`Memory`] whenever possible.
179///
180/// ## `Memory` Safety and Threads
181///
182/// Currently the `wasmtime` crate does not implement the wasm threads proposal,
183/// but it is planned to do so. It may be interesting to readers to see how this
184/// affects memory safety and what was previously just discussed as well.
185///
186/// Once threads are added into the mix, all of the above rules still apply.
187/// There's an additional consideration that all reads and writes can happen
188/// concurrently, though. This effectively means that any borrow into wasm
189/// memory are virtually never safe to have.
190///
191/// Mutable pointers are fundamentally unsafe to have in a concurrent scenario
192/// in the face of arbitrary wasm code. Only if you dynamically know for sure
193/// that wasm won't access a region would it be safe to construct a mutable
194/// pointer. Additionally even shared pointers are largely unsafe because their
195/// underlying contents may change, so unless `UnsafeCell` in one form or
196/// another is used everywhere there's no safety.
197///
198/// One important point about concurrency is that while [`Memory::grow`] can
199/// happen concurrently it will never relocate the base pointer. Shared
200/// memories must always have a maximum size and they will be preallocated such
201/// that growth will never relocate the base pointer. The current size of the
202/// memory may still change over time though.
203///
204/// Overall the general rule of thumb for shared memories is that you must
205/// atomically read and write everything. Nothing can be borrowed and everything
206/// must be eagerly copied out. This means that [`Memory::data`] and
207/// [`Memory::data_mut`] won't work in the future (they'll probably return an
208/// error) for shared memories when they're implemented. When possible it's
209/// recommended to use [`Memory::read`] and [`Memory::write`] which will still
210/// be provided.
211#[derive(Copy, Clone, Debug)]
212#[repr(C)] // here for the C API
213pub struct Memory {
214    /// The internal store instance that this memory belongs to.
215    instance: StoreInstanceId,
216    /// The index of the memory, within `instance` above, that this memory
217    /// refers to.
218    index: DefinedMemoryIndex,
219}
220
221// Double-check that the C representation in `extern.h` matches our in-Rust
222// representation here in terms of size/alignment/etc.
223const _: () = {
224    #[repr(C)]
225    struct Tmp(u64, u32);
226    #[repr(C)]
227    struct C(Tmp, u32);
228    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Memory>());
229    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Memory>());
230    assert!(core::mem::offset_of!(Memory, instance) == 0);
231};
232
233impl Memory {
234    /// Creates a new WebAssembly memory given the configuration of `ty`.
235    ///
236    /// The `store` argument will be the owner of the returned [`Memory`]. All
237    /// WebAssembly memory is initialized to zero.
238    ///
239    /// # Panics
240    ///
241    /// This function will panic if the [`Store`](`crate::Store`) has a
242    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
243    /// [`Store::limiter_async`](`crate::Store::limiter_async`)). When
244    /// using an async resource limiter, use [`Memory::new_async`] instead.
245    ///
246    /// # Examples
247    ///
248    /// ```
249    /// # use wasmtime::*;
250    /// # fn main() -> anyhow::Result<()> {
251    /// let engine = Engine::default();
252    /// let mut store = Store::new(&engine, ());
253    ///
254    /// let memory_ty = MemoryType::new(1, None);
255    /// let memory = Memory::new(&mut store, memory_ty)?;
256    ///
257    /// let module = Module::new(&engine, "(module (memory (import \"\" \"\") 1))")?;
258    /// let instance = Instance::new(&mut store, &module, &[memory.into()])?;
259    /// // ...
260    /// # Ok(())
261    /// # }
262    /// ```
263    pub fn new(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
264        Self::_new(store.as_context_mut().0, ty)
265    }
266
267    /// Async variant of [`Memory::new`]. You must use this variant with
268    /// [`Store`](`crate::Store`)s which have a
269    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
270    ///
271    /// # Panics
272    ///
273    /// This function will panic when used with a non-async
274    /// [`Store`](`crate::Store`).
275    #[cfg(feature = "async")]
276    pub async fn new_async(
277        mut store: impl AsContextMut<Data: Send>,
278        ty: MemoryType,
279    ) -> Result<Memory> {
280        let mut store = store.as_context_mut();
281        assert!(
282            store.0.async_support(),
283            "cannot use `new_async` without enabling async support on the config"
284        );
285        store.on_fiber(|store| Self::_new(store.0, ty)).await?
286    }
287
288    /// Helper function for attaching the memory to a "frankenstein" instance
289    fn _new(store: &mut StoreOpaque, ty: MemoryType) -> Result<Memory> {
290        unsafe {
291            let export = generate_memory_export(store, &ty, None)?;
292            Ok(Memory::from_wasmtime_memory(export, store))
293        }
294    }
295
296    /// Returns the underlying type of this memory.
297    ///
298    /// # Panics
299    ///
300    /// Panics if this memory doesn't belong to `store`.
301    ///
302    /// # Examples
303    ///
304    /// ```
305    /// # use wasmtime::*;
306    /// # fn main() -> anyhow::Result<()> {
307    /// let engine = Engine::default();
308    /// let mut store = Store::new(&engine, ());
309    /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1))")?;
310    /// let instance = Instance::new(&mut store, &module, &[])?;
311    /// let memory = instance.get_memory(&mut store, "mem").unwrap();
312    /// let ty = memory.ty(&store);
313    /// assert_eq!(ty.minimum(), 1);
314    /// # Ok(())
315    /// # }
316    /// ```
317    pub fn ty(&self, store: impl AsContext) -> MemoryType {
318        let store = store.as_context();
319        MemoryType::from_wasmtime_memory(self.wasmtime_ty(store.0))
320    }
321
322    /// Safely reads memory contents at the given offset into a buffer.
323    ///
324    /// The entire buffer will be filled.
325    ///
326    /// If `offset + buffer.len()` exceed the current memory capacity, then the
327    /// buffer is left untouched and a [`MemoryAccessError`] is returned.
328    ///
329    /// # Panics
330    ///
331    /// Panics if this memory doesn't belong to `store`.
332    pub fn read(
333        &self,
334        store: impl AsContext,
335        offset: usize,
336        buffer: &mut [u8],
337    ) -> Result<(), MemoryAccessError> {
338        let store = store.as_context();
339        let slice = self
340            .data(&store)
341            .get(offset..)
342            .and_then(|s| s.get(..buffer.len()))
343            .ok_or(MemoryAccessError { _private: () })?;
344        buffer.copy_from_slice(slice);
345        Ok(())
346    }
347
348    /// Safely writes contents of a buffer to this memory at the given offset.
349    ///
350    /// If the `offset + buffer.len()` exceeds the current memory capacity, then
351    /// none of the buffer is written to memory and a [`MemoryAccessError`] is
352    /// returned.
353    ///
354    /// # Panics
355    ///
356    /// Panics if this memory doesn't belong to `store`.
357    pub fn write(
358        &self,
359        mut store: impl AsContextMut,
360        offset: usize,
361        buffer: &[u8],
362    ) -> Result<(), MemoryAccessError> {
363        let mut context = store.as_context_mut();
364        self.data_mut(&mut context)
365            .get_mut(offset..)
366            .and_then(|s| s.get_mut(..buffer.len()))
367            .ok_or(MemoryAccessError { _private: () })?
368            .copy_from_slice(buffer);
369        Ok(())
370    }
371
372    /// Returns this memory as a native Rust slice.
373    ///
374    /// Note that this method will consider the entire store context provided as
375    /// borrowed for the duration of the lifetime of the returned slice.
376    ///
377    /// # Panics
378    ///
379    /// Panics if this memory doesn't belong to `store`.
380    pub fn data<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a [u8] {
381        unsafe {
382            let store = store.into();
383            let definition = store[self.instance].memory(self.index);
384            debug_assert!(!self.ty(store).is_shared());
385            slice::from_raw_parts(definition.base.as_ptr(), definition.current_length())
386        }
387    }
388
389    /// Returns this memory as a native Rust mutable slice.
390    ///
391    /// Note that this method will consider the entire store context provided as
392    /// borrowed for the duration of the lifetime of the returned slice.
393    ///
394    /// # Panics
395    ///
396    /// Panics if this memory doesn't belong to `store`.
397    pub fn data_mut<'a, T: 'static>(
398        &self,
399        store: impl Into<StoreContextMut<'a, T>>,
400    ) -> &'a mut [u8] {
401        unsafe {
402            let store = store.into();
403            let definition = store[self.instance].memory(self.index);
404            debug_assert!(!self.ty(store).is_shared());
405            slice::from_raw_parts_mut(definition.base.as_ptr(), definition.current_length())
406        }
407    }
408
409    /// Same as [`Memory::data_mut`], but also returns the `T` from the
410    /// [`StoreContextMut`].
411    ///
412    /// This method can be used when you want to simultaneously work with the
413    /// `T` in the store as well as the memory behind this [`Memory`]. Using
414    /// [`Memory::data_mut`] would consider the entire store borrowed, whereas
415    /// this method allows the Rust compiler to see that the borrow of this
416    /// memory and the borrow of `T` are disjoint.
417    ///
418    /// # Panics
419    ///
420    /// Panics if this memory doesn't belong to `store`.
421    pub fn data_and_store_mut<'a, T: 'static>(
422        &self,
423        store: impl Into<StoreContextMut<'a, T>>,
424    ) -> (&'a mut [u8], &'a mut T) {
425        // Note the unsafety here. Our goal is to simultaneously borrow the
426        // memory and custom data from `store`, and the store it's connected
427        // to. Rust will not let us do that, however, because we must call two
428        // separate methods (both of which borrow the whole `store`) and one of
429        // our borrows is mutable (the custom data).
430        //
431        // This operation, however, is safe because these borrows do not overlap
432        // and in the process of borrowing them mutability doesn't actually
433        // touch anything. This is akin to mutably borrowing two indices in an
434        // array, which is safe so long as the indices are separate.
435        unsafe {
436            let mut store = store.into();
437            let data = &mut *(store.data_mut() as *mut T);
438            (self.data_mut(store), data)
439        }
440    }
441
442    /// Returns the base pointer, in the host's address space, that the memory
443    /// is located at.
444    ///
445    /// For more information and examples see the documentation on the
446    /// [`Memory`] type.
447    ///
448    /// # Panics
449    ///
450    /// Panics if this memory doesn't belong to `store`.
451    pub fn data_ptr(&self, store: impl AsContext) -> *mut u8 {
452        store.as_context()[self.instance]
453            .memory(self.index)
454            .base
455            .as_ptr()
456    }
457
458    /// Returns the byte length of this memory.
459    ///
460    /// WebAssembly memories are made up of a whole number of pages, so the byte
461    /// size returned will always be a multiple of this memory's page size. Note
462    /// that different Wasm memories may have different page sizes. You can get
463    /// a memory's page size via the [`Memory::page_size`] method.
464    ///
465    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
466    /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
467    /// into a page size of `1`. Future extensions might allow any power of two
468    /// as a page size.
469    ///
470    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
471    ///
472    /// For more information and examples see the documentation on the
473    /// [`Memory`] type.
474    ///
475    /// # Panics
476    ///
477    /// Panics if this memory doesn't belong to `store`.
478    pub fn data_size(&self, store: impl AsContext) -> usize {
479        self.internal_data_size(store.as_context().0)
480    }
481
482    pub(crate) fn internal_data_size(&self, store: &StoreOpaque) -> usize {
483        store[self.instance].memory(self.index).current_length()
484    }
485
486    /// Returns the size, in units of pages, of this Wasm memory.
487    ///
488    /// WebAssembly memories are made up of a whole number of pages, so the byte
489    /// size returned will always be a multiple of this memory's page size. Note
490    /// that different Wasm memories may have different page sizes. You can get
491    /// a memory's page size via the [`Memory::page_size`] method.
492    ///
493    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
494    /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
495    /// into a page size of `1`. Future extensions might allow any power of two
496    /// as a page size.
497    ///
498    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
499    ///
500    /// # Panics
501    ///
502    /// Panics if this memory doesn't belong to `store`.
503    pub fn size(&self, store: impl AsContext) -> u64 {
504        self.internal_size(store.as_context().0)
505    }
506
507    pub(crate) fn internal_size(&self, store: &StoreOpaque) -> u64 {
508        let byte_size = self.internal_data_size(store);
509        let page_size = usize::try_from(self._page_size(store)).unwrap();
510        u64::try_from(byte_size / page_size).unwrap()
511    }
512
513    /// Returns the size of a page, in bytes, for this memory.
514    ///
515    /// WebAssembly memories are made up of a whole number of pages, so the byte
516    /// size (as returned by [`Memory::data_size`]) will always be a multiple of
517    /// their page size. Different Wasm memories may have different page sizes.
518    ///
519    /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
520    /// but [the custom-page-sizes proposal] allows opting into a page size of
521    /// `1`. Future extensions might allow any power of two as a page size.
522    ///
523    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
524    pub fn page_size(&self, store: impl AsContext) -> u64 {
525        self._page_size(store.as_context().0)
526    }
527
528    pub(crate) fn _page_size(&self, store: &StoreOpaque) -> u64 {
529        self.wasmtime_ty(store).page_size()
530    }
531
532    /// Returns the log2 of this memory's page size, in bytes.
533    ///
534    /// WebAssembly memories are made up of a whole number of pages, so the byte
535    /// size (as returned by [`Memory::data_size`]) will always be a multiple of
536    /// their page size. Different Wasm memories may have different page sizes.
537    ///
538    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
539    /// `65536`) but [the custom-page-sizes proposal] allows opting into a page
540    /// size of `1`. Future extensions might allow any power of two as a page
541    /// size.
542    ///
543    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
544    pub fn page_size_log2(&self, store: impl AsContext) -> u8 {
545        self._page_size_log2(store.as_context().0)
546    }
547
548    pub(crate) fn _page_size_log2(&self, store: &StoreOpaque) -> u8 {
549        self.wasmtime_ty(store).page_size_log2
550    }
551
552    /// Grows this WebAssembly memory by `delta` pages.
553    ///
554    /// This will attempt to add `delta` more pages of memory on to the end of
555    /// this `Memory` instance. If successful this may relocate the memory and
556    /// cause [`Memory::data_ptr`] to return a new value. Additionally any
557    /// unsafely constructed slices into this memory may no longer be valid.
558    ///
559    /// On success returns the number of pages this memory previously had
560    /// before the growth succeeded.
561    ///
562    /// Note that, by default, a WebAssembly memory's page size is 64KiB (aka
563    /// 65536 or 2<sup>16</sup>). The [custom-page-sizes proposal] allows Wasm
564    /// memories to opt into a page size of one byte (and this may be further
565    /// relaxed to any power of two in a future extension).
566    ///
567    /// [custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
568    ///
569    /// # Errors
570    ///
571    /// Returns an error if memory could not be grown, for example if it exceeds
572    /// the maximum limits of this memory. A
573    /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
574    /// preventing a memory to grow.
575    ///
576    /// # Panics
577    ///
578    /// Panics if this memory doesn't belong to `store`.
579    ///
580    /// This function will panic if the [`Store`](`crate::Store`) has a
581    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
582    /// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an
583    /// async resource limiter, use [`Memory::grow_async`] instead.
584    ///
585    /// # Examples
586    ///
587    /// ```
588    /// # use wasmtime::*;
589    /// # fn main() -> anyhow::Result<()> {
590    /// let engine = Engine::default();
591    /// let mut store = Store::new(&engine, ());
592    /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1 2))")?;
593    /// let instance = Instance::new(&mut store, &module, &[])?;
594    /// let memory = instance.get_memory(&mut store, "mem").unwrap();
595    ///
596    /// assert_eq!(memory.size(&store), 1);
597    /// assert_eq!(memory.grow(&mut store, 1)?, 1);
598    /// assert_eq!(memory.size(&store), 2);
599    /// assert!(memory.grow(&mut store, 1).is_err());
600    /// assert_eq!(memory.size(&store), 2);
601    /// assert_eq!(memory.grow(&mut store, 0)?, 2);
602    /// # Ok(())
603    /// # }
604    /// ```
605    pub fn grow(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
606        let store = store.as_context_mut().0;
607        let mem = self.wasmtime_memory(store);
608        unsafe {
609            match (*mem).grow(delta, Some(store))? {
610                Some(size) => {
611                    let vm = (*mem).vmmemory();
612                    store[self.instance].memory_ptr(self.index).write(vm);
613                    let page_size = (*mem).page_size();
614                    Ok(u64::try_from(size).unwrap() / page_size)
615                }
616                None => bail!("failed to grow memory by `{}`", delta),
617            }
618        }
619    }
620
621    /// Async variant of [`Memory::grow`]. Required when using a
622    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
623    ///
624    /// # Panics
625    ///
626    /// This function will panic when used with a non-async
627    /// [`Store`](`crate::Store`).
628    #[cfg(feature = "async")]
629    pub async fn grow_async(
630        &self,
631        mut store: impl AsContextMut<Data: Send>,
632        delta: u64,
633    ) -> Result<u64> {
634        let mut store = store.as_context_mut();
635        assert!(
636            store.0.async_support(),
637            "cannot use `grow_async` without enabling async support on the config"
638        );
639        store.on_fiber(|store| self.grow(store, delta)).await?
640    }
641
642    fn wasmtime_memory(&self, store: &mut StoreOpaque) -> *mut crate::runtime::vm::Memory {
643        self.instance.get_mut(store).get_defined_memory(self.index)
644    }
645
646    pub(crate) unsafe fn from_wasmtime_memory(
647        wasmtime_export: crate::runtime::vm::ExportMemory,
648        store: &StoreOpaque,
649    ) -> Memory {
650        Memory {
651            instance: store.vmctx_id(wasmtime_export.vmctx),
652            index: wasmtime_export.index,
653        }
654    }
655
656    pub(crate) fn wasmtime_ty<'a>(&self, store: &'a StoreOpaque) -> &'a wasmtime_environ::Memory {
657        let module = store[self.instance].env_module();
658        let index = module.memory_index(self.index);
659        &module.memories[index]
660    }
661
662    pub(crate) fn vmimport(&self, store: &StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
663        let instance = &store[self.instance];
664        crate::runtime::vm::VMMemoryImport {
665            from: instance.memory_ptr(self.index).into(),
666            vmctx: instance.vmctx().into(),
667            index: self.index,
668        }
669    }
670
671    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
672        store.id() == self.instance.store_id()
673    }
674
675    /// Get a stable hash key for this memory.
676    ///
677    /// Even if the same underlying memory definition is added to the
678    /// `StoreData` multiple times and becomes multiple `wasmtime::Memory`s,
679    /// this hash key will be consistent across all of these memories.
680    #[cfg(feature = "coredump")]
681    pub(crate) fn hash_key(&self, store: &StoreOpaque) -> impl core::hash::Hash + Eq + use<> {
682        store[self.instance].memory_ptr(self.index).as_ptr().addr()
683    }
684}
685
686/// A linear memory. This trait provides an interface for raw memory buffers
687/// which are used by wasmtime, e.g. inside ['Memory']. Such buffers are in
688/// principle not thread safe. By implementing this trait together with
689/// MemoryCreator, one can supply wasmtime with custom allocated host managed
690/// memory.
691///
692/// # Safety
693///
694/// The memory should be page aligned and a multiple of page size.
695/// To prevent possible silent overflows, the memory should be protected by a
696/// guard page.  Additionally the safety concerns explained in ['Memory'], for
697/// accessing the memory apply here as well.
698///
699/// Note that this is a relatively advanced feature and it is recommended to be
700/// familiar with wasmtime runtime code to use it.
701pub unsafe trait LinearMemory: Send + Sync + 'static {
702    /// Returns the number of allocated bytes which are accessible at this time.
703    fn byte_size(&self) -> usize;
704
705    /// Returns byte capacity of this linear memory's current allocation.
706    ///
707    /// Growth up to this value should not relocate the linear memory base
708    /// pointer.
709    fn byte_capacity(&self) -> usize;
710
711    /// Grows this memory to have the `new_size`, in bytes, specified.
712    ///
713    /// Returns `Err` if memory can't be grown by the specified amount
714    /// of bytes. The error may be downcastable to `std::io::Error`.
715    /// Returns `Ok` if memory was grown successfully.
716    fn grow_to(&mut self, new_size: usize) -> Result<()>;
717
718    /// Return the allocated memory as a mutable pointer to u8.
719    fn as_ptr(&self) -> *mut u8;
720}
721
722/// A memory creator. Can be used to provide a memory creator
723/// to wasmtime which supplies host managed memory.
724///
725/// # Safety
726///
727/// This trait is unsafe, as the memory safety depends on proper implementation
728/// of memory management. Memories created by the MemoryCreator should always be
729/// treated as owned by wasmtime instance, and any modification of them outside
730/// of wasmtime invoked routines is unsafe and may lead to corruption.
731///
732/// Note that this is a relatively advanced feature and it is recommended to be
733/// familiar with Wasmtime runtime code to use it.
734pub unsafe trait MemoryCreator: Send + Sync {
735    /// Create a new `LinearMemory` object from the specified parameters.
736    ///
737    /// The type of memory being created is specified by `ty` which indicates
738    /// both the minimum and maximum size, in wasm pages. The minimum and
739    /// maximum sizes, in bytes, are also specified as parameters to avoid
740    /// integer conversion if desired.
741    ///
742    /// The `reserved_size_in_bytes` value indicates the expected size of the
743    /// reservation that is to be made for this memory. If this value is `None`
744    /// than the implementation is free to allocate memory as it sees fit. If
745    /// the value is `Some`, however, then the implementation is expected to
746    /// reserve that many bytes for the memory's allocation, plus the guard
747    /// size at the end. Note that this reservation need only be a virtual
748    /// memory reservation, physical memory does not need to be allocated
749    /// immediately. In this case `grow` should never move the base pointer and
750    /// the maximum size of `ty` is guaranteed to fit within
751    /// `reserved_size_in_bytes`.
752    ///
753    /// The `guard_size_in_bytes` parameter indicates how many bytes of space,
754    /// after the memory allocation, is expected to be unmapped. JIT code will
755    /// elide bounds checks based on the `guard_size_in_bytes` provided, so for
756    /// JIT code to work correctly the memory returned will need to be properly
757    /// guarded with `guard_size_in_bytes` bytes left unmapped after the base
758    /// allocation.
759    ///
760    /// Note that the `reserved_size_in_bytes` and `guard_size_in_bytes` options
761    /// are tuned from the various [`Config`](crate::Config) methods about
762    /// memory sizes/guards. Additionally these two values are guaranteed to be
763    /// multiples of the system page size.
764    ///
765    /// Memory created from this method should be zero filled.
766    fn new_memory(
767        &self,
768        ty: MemoryType,
769        minimum: usize,
770        maximum: Option<usize>,
771        reserved_size_in_bytes: Option<usize>,
772        guard_size_in_bytes: usize,
773    ) -> Result<Box<dyn LinearMemory>, String>;
774}
775
776/// A constructor for externally-created shared memory.
777///
778/// The [threads proposal] adds the concept of "shared memory" to WebAssembly.
779/// This is much the same as a Wasm linear memory (i.e., [`Memory`]), but can be
780/// used concurrently by multiple agents. Because these agents may execute in
781/// different threads, [`SharedMemory`] must be thread-safe.
782///
783/// When the threads proposal is enabled, there are multiple ways to construct
784/// shared memory:
785///  1. for imported shared memory, e.g., `(import "env" "memory" (memory 1 1
786///     shared))`, the user must supply a [`SharedMemory`] with the
787///     externally-created memory as an import to the instance--e.g.,
788///     `shared_memory.into()`.
789///  2. for private or exported shared memory, e.g., `(export "env" "memory"
790///     (memory 1 1 shared))`, Wasmtime will create the memory internally during
791///     instantiation--access using `Instance::get_shared_memory()`.
792///
793/// [threads proposal]:
794///     https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md
795///
796/// # Examples
797///
798/// ```
799/// # use wasmtime::*;
800/// # fn main() -> anyhow::Result<()> {
801/// let mut config = Config::new();
802/// config.wasm_threads(true);
803/// let engine = Engine::new(&config)?;
804/// let mut store = Store::new(&engine, ());
805///
806/// let shared_memory = SharedMemory::new(&engine, MemoryType::shared(1, 2))?;
807/// let module = Module::new(&engine, r#"(module (memory (import "" "") 1 2 shared))"#)?;
808/// let instance = Instance::new(&mut store, &module, &[shared_memory.into()])?;
809/// // ...
810/// # Ok(())
811/// # }
812/// ```
813#[derive(Clone)]
814pub struct SharedMemory {
815    vm: crate::runtime::vm::SharedMemory,
816    engine: Engine,
817    page_size_log2: u8,
818}
819
820impl SharedMemory {
821    /// Construct a [`SharedMemory`] by providing both the `minimum` and
822    /// `maximum` number of 64K-sized pages. This call allocates the necessary
823    /// pages on the system.
824    #[cfg(feature = "threads")]
825    pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self> {
826        if !ty.is_shared() {
827            bail!("shared memory must have the `shared` flag enabled on its memory type")
828        }
829        debug_assert!(ty.maximum().is_some());
830
831        let tunables = engine.tunables();
832        let ty = ty.wasmtime_memory();
833        let page_size_log2 = ty.page_size_log2;
834        let memory = crate::runtime::vm::SharedMemory::new(ty, tunables)?;
835
836        Ok(Self {
837            vm: memory,
838            engine: engine.clone(),
839            page_size_log2,
840        })
841    }
842
843    /// Return the type of the shared memory.
844    pub fn ty(&self) -> MemoryType {
845        MemoryType::from_wasmtime_memory(&self.vm.ty())
846    }
847
848    /// Returns the size, in WebAssembly pages, of this wasm memory.
849    pub fn size(&self) -> u64 {
850        let byte_size = u64::try_from(self.data_size()).unwrap();
851        let page_size = u64::from(self.page_size());
852        byte_size / page_size
853    }
854
855    /// Returns the size of a page, in bytes, for this memory.
856    ///
857    /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
858    /// but [the custom-page-sizes proposal] allows opting into a page size of
859    /// `1`. Future extensions might allow any power of two as a page size.
860    ///
861    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
862    pub fn page_size(&self) -> u32 {
863        debug_assert!(self.page_size_log2 == 0 || self.page_size_log2 == 16);
864        1 << self.page_size_log2
865    }
866
867    /// Returns the byte length of this memory.
868    ///
869    /// The returned value will be a multiple of the wasm page size, 64k.
870    ///
871    /// For more information and examples see the documentation on the
872    /// [`Memory`] type.
873    pub fn data_size(&self) -> usize {
874        self.vm.byte_size()
875    }
876
877    /// Return access to the available portion of the shared memory.
878    ///
879    /// The slice returned represents the region of accessible memory at the
880    /// time that this function was called. The contents of the returned slice
881    /// will reflect concurrent modifications happening on other threads.
882    ///
883    /// # Safety
884    ///
885    /// The returned slice is valid for the entire duration of the lifetime of
886    /// this instance of [`SharedMemory`]. The base pointer of a shared memory
887    /// does not change. This [`SharedMemory`] may grow further after this
888    /// function has been called, but the slice returned will not grow.
889    ///
890    /// Concurrent modifications may be happening to the data returned on other
891    /// threads. The `UnsafeCell<u8>` represents that safe access to the
892    /// contents of the slice is not possible through normal loads and stores.
893    ///
894    /// The memory returned must be accessed safely through the `Atomic*` types
895    /// in the [`std::sync::atomic`] module. Casting to those types must
896    /// currently be done unsafely.
897    pub fn data(&self) -> &[UnsafeCell<u8>] {
898        unsafe {
899            let definition = self.vm.vmmemory_ptr().as_ref();
900            slice::from_raw_parts(definition.base.as_ptr().cast(), definition.current_length())
901        }
902    }
903
904    /// Grows this WebAssembly memory by `delta` pages.
905    ///
906    /// This will attempt to add `delta` more pages of memory on to the end of
907    /// this `Memory` instance. If successful this may relocate the memory and
908    /// cause [`Memory::data_ptr`] to return a new value. Additionally any
909    /// unsafely constructed slices into this memory may no longer be valid.
910    ///
911    /// On success returns the number of pages this memory previously had
912    /// before the growth succeeded.
913    ///
914    /// # Errors
915    ///
916    /// Returns an error if memory could not be grown, for example if it exceeds
917    /// the maximum limits of this memory. A
918    /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
919    /// preventing a memory to grow.
920    pub fn grow(&self, delta: u64) -> Result<u64> {
921        match self.vm.grow(delta, None)? {
922            Some((old_size, _new_size)) => {
923                // For shared memory, the `VMMemoryDefinition` is updated inside
924                // the locked region.
925                Ok(u64::try_from(old_size).unwrap() / u64::from(self.page_size()))
926            }
927            None => bail!("failed to grow memory by `{}`", delta),
928        }
929    }
930
931    /// Equivalent of the WebAssembly `memory.atomic.notify` instruction for
932    /// this shared memory.
933    ///
934    /// This method allows embedders to notify threads blocked on the specified
935    /// `addr`, an index into wasm linear memory. Threads could include
936    /// wasm threads blocked on a `memory.atomic.wait*` instruction or embedder
937    /// threads blocked on [`SharedMemory::atomic_wait32`], for example.
938    ///
939    /// The `count` argument is the number of threads to wake up.
940    ///
941    /// This function returns the number of threads awoken.
942    ///
943    /// # Errors
944    ///
945    /// This function will return an error if `addr` is not within bounds or
946    /// not aligned to a 4-byte boundary.
947    pub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap> {
948        self.vm.atomic_notify(addr, count)
949    }
950
951    /// Equivalent of the WebAssembly `memory.atomic.wait32` instruction for
952    /// this shared memory.
953    ///
954    /// This method allows embedders to block the current thread until notified
955    /// via the `memory.atomic.notify` instruction or the
956    /// [`SharedMemory::atomic_notify`] method, enabling synchronization with
957    /// the wasm guest as desired.
958    ///
959    /// The `expected` argument is the expected 32-bit value to be stored at
960    /// the byte address `addr` specified. The `addr` specified is an index
961    /// into this linear memory.
962    ///
963    /// The optional `timeout` argument is the maximum amount of time to block
964    /// the current thread. If not specified the thread may sleep indefinitely.
965    ///
966    /// This function returns one of three possible values:
967    ///
968    /// * `WaitResult::Ok` - this function, loaded the value at `addr`, found
969    ///   it was equal to `expected`, and then blocked (all as one atomic
970    ///   operation). The thread was then awoken with a `memory.atomic.notify`
971    ///   instruction or the [`SharedMemory::atomic_notify`] method.
972    /// * `WaitResult::Mismatch` - the value at `addr` was loaded but was not
973    ///   equal to `expected` so the thread did not block and immediately
974    ///   returned.
975    /// * `WaitResult::TimedOut` - all the steps of `Ok` happened, except this
976    ///   thread was woken up due to a timeout.
977    ///
978    /// This function will not return due to spurious wakeups.
979    ///
980    /// # Errors
981    ///
982    /// This function will return an error if `addr` is not within bounds or
983    /// not aligned to a 4-byte boundary.
984    pub fn atomic_wait32(
985        &self,
986        addr: u64,
987        expected: u32,
988        timeout: Option<Duration>,
989    ) -> Result<WaitResult, Trap> {
990        self.vm.atomic_wait32(addr, expected, timeout)
991    }
992
993    /// Equivalent of the WebAssembly `memory.atomic.wait64` instruction for
994    /// this shared memory.
995    ///
996    /// For more information see [`SharedMemory::atomic_wait32`].
997    ///
998    /// # Errors
999    ///
1000    /// Returns the same error as [`SharedMemory::atomic_wait32`] except that
1001    /// the specified address must be 8-byte aligned instead of 4-byte aligned.
1002    pub fn atomic_wait64(
1003        &self,
1004        addr: u64,
1005        expected: u64,
1006        timeout: Option<Duration>,
1007    ) -> Result<WaitResult, Trap> {
1008        self.vm.atomic_wait64(addr, expected, timeout)
1009    }
1010
1011    /// Return a reference to the [`Engine`] used to configure the shared
1012    /// memory.
1013    pub(crate) fn engine(&self) -> &Engine {
1014        &self.engine
1015    }
1016
1017    /// Construct a single-memory instance to provide a way to import
1018    /// [`SharedMemory`] into other modules.
1019    pub(crate) fn vmimport(&self, store: &mut StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
1020        let export_memory = generate_memory_export(store, &self.ty(), Some(&self.vm)).unwrap();
1021        VMMemoryImport {
1022            from: export_memory.definition.into(),
1023            vmctx: export_memory.vmctx.into(),
1024            index: export_memory.index,
1025        }
1026    }
1027
1028    /// Create a [`SharedMemory`] from an [`ExportMemory`] definition. This
1029    /// function is available to handle the case in which a Wasm module exports
1030    /// shared memory and the user wants host-side access to it.
1031    pub(crate) unsafe fn from_wasmtime_memory(
1032        wasmtime_export: crate::runtime::vm::ExportMemory,
1033        store: &StoreOpaque,
1034    ) -> Self {
1035        #[cfg_attr(not(feature = "threads"), allow(unused_variables, unreachable_code))]
1036        crate::runtime::vm::Instance::from_vmctx(wasmtime_export.vmctx, |handle| {
1037            let memory_index = handle.env_module().memory_index(wasmtime_export.index);
1038            let page_size = handle.memory_page_size(memory_index);
1039            debug_assert!(page_size.is_power_of_two());
1040            let page_size_log2 = u8::try_from(page_size.ilog2()).unwrap();
1041
1042            let memory = handle
1043                .get_defined_memory(wasmtime_export.index)
1044                .as_mut()
1045                .unwrap();
1046            match memory.as_shared_memory() {
1047                Some(mem) => Self {
1048                    vm: mem.clone(),
1049                    engine: store.engine().clone(),
1050                    page_size_log2,
1051                },
1052                None => panic!("unable to convert from a shared memory"),
1053            }
1054        })
1055    }
1056}
1057
1058impl fmt::Debug for SharedMemory {
1059    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1060        f.debug_struct("SharedMemory").finish_non_exhaustive()
1061    }
1062}
1063
1064#[cfg(test)]
1065mod tests {
1066    use crate::*;
1067
1068    // Assert that creating a memory via `Memory::new` respects the limits/tunables
1069    // in `Config`.
1070    #[test]
1071    fn respect_tunables() {
1072        let mut cfg = Config::new();
1073        cfg.memory_reservation(0).memory_guard_size(0);
1074        let mut store = Store::new(&Engine::new(&cfg).unwrap(), ());
1075        let ty = MemoryType::new(1, None);
1076        let mem = Memory::new(&mut store, ty).unwrap();
1077        let store = store.as_context();
1078        let tunables = store.engine().tunables();
1079        assert_eq!(tunables.memory_guard_size, 0);
1080        assert!(
1081            !mem.wasmtime_ty(store.0)
1082                .can_elide_bounds_check(tunables, 12)
1083        );
1084    }
1085
1086    #[test]
1087    fn hash_key_is_stable_across_duplicate_store_data_entries() -> Result<()> {
1088        let mut store = Store::<()>::default();
1089        let module = Module::new(
1090            store.engine(),
1091            r#"
1092                (module
1093                    (memory (export "m") 1 1)
1094                )
1095            "#,
1096        )?;
1097        let instance = Instance::new(&mut store, &module, &[])?;
1098
1099        // Each time we `get_memory`, we call `Memory::from_wasmtime` which adds
1100        // a new entry to `StoreData`, so `g1` and `g2` will have different
1101        // indices into `StoreData`.
1102        let m1 = instance.get_memory(&mut store, "m").unwrap();
1103        let m2 = instance.get_memory(&mut store, "m").unwrap();
1104
1105        // That said, they really point to the same memory.
1106        assert_eq!(m1.data(&store)[0], 0);
1107        assert_eq!(m2.data(&store)[0], 0);
1108        m1.data_mut(&mut store)[0] = 42;
1109        assert_eq!(m1.data(&mut store)[0], 42);
1110        assert_eq!(m2.data(&mut store)[0], 42);
1111
1112        // And therefore their hash keys are the same.
1113        assert!(m1.hash_key(&store.as_context().0) == m2.hash_key(&store.as_context().0));
1114
1115        // But the hash keys are different from different memories.
1116        let instance2 = Instance::new(&mut store, &module, &[])?;
1117        let m3 = instance2.get_memory(&mut store, "m").unwrap();
1118        assert!(m1.hash_key(&store.as_context().0) != m3.hash_key(&store.as_context().0));
1119
1120        Ok(())
1121    }
1122}