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