wasmtime/runtime/

memory.rs

use crate::Trap;
use crate::prelude::*;
use crate::runtime::vm::{self, ExportMemory};
use crate::store::{StoreInstanceId, StoreOpaque, StoreResourceLimiter};
use crate::trampoline::generate_memory_export;
#[cfg(feature = "async")]
use crate::vm::VMStore;
use crate::{AsContext, AsContextMut, Engine, MemoryType, StoreContext, StoreContextMut};
use alloc::sync::Arc;
use core::any::Any;
use core::cell::UnsafeCell;
use core::fmt;
use core::slice;
use core::time::Duration;
use wasmtime_environ::{DefinedMemoryIndex, MemoryTunables};

pub use crate::runtime::vm::WaitResult;

/// Error for out of bounds [`Memory`] access.
#[derive(Debug)]
#[non_exhaustive]
pub struct MemoryAccessError {
    // Keep struct internals private for future extensibility.
    _private: (),
}

impl fmt::Display for MemoryAccessError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "out of bounds memory access")
    }
}

impl core::error::Error for MemoryAccessError {}

/// A WebAssembly linear memory.
///
/// WebAssembly memories represent a contiguous array of bytes that have a size
/// that is always a multiple of the WebAssembly page size, currently 64
/// kilobytes.
///
/// WebAssembly memory is used for global data (not to be confused with wasm
/// `global` items), statics in C/C++/Rust, shadow stack memory, etc. Accessing
/// wasm memory is generally quite fast.
///
/// Memories, like other wasm items, are owned by a [`Store`](crate::Store).
///
/// # `Memory` and Safety
///
/// Linear memory is a lynchpin of safety for WebAssembly. In Wasmtime there are
/// safe methods of interacting with a [`Memory`]:
///
/// * [`Memory::read`]
/// * [`Memory::write`]
/// * [`Memory::data`]
/// * [`Memory::data_mut`]
///
/// Note that all of these consider the entire store context as borrowed for the
/// duration of the call or the duration of the returned slice. This largely
/// means that while the function is running you'll be unable to borrow anything
/// else from the store. This includes getting access to the `T` on
/// [`Store<T>`](crate::Store), but it also means that you can't recursively
/// call into WebAssembly for instance.
///
/// If you'd like to dip your toes into handling [`Memory`] in a more raw
/// fashion (e.g. by using raw pointers or raw slices), then there's a few
/// important points to consider when doing so:
///
/// * Any recursive calls into WebAssembly can possibly modify any byte of the
///   entire memory. This means that whenever wasm is called Rust can't have any
///   long-lived borrows live across the wasm function call. Slices like `&mut
///   [u8]` will be violated because they're not actually exclusive at that
///   point, and slices like `&[u8]` are also violated because their contents
///   may be mutated.
///
/// * WebAssembly memories can grow, and growth may change the base pointer.
///   This means that even holding a raw pointer to memory over a wasm function
///   call is also incorrect. Anywhere in the function call the base address of
///   memory may change. Note that growth can also be requested from the
///   embedding API as well.
///
/// As a general rule of thumb it's recommended to stick to the safe methods of
/// [`Memory`] if you can. It's not advised to use raw pointers or `unsafe`
/// operations because of how easy it is to accidentally get things wrong.
///
/// Some examples of safely interacting with memory are:
///
/// ```rust
/// use wasmtime::{Memory, Store, MemoryAccessError};
///
/// // Memory can be read and written safely with the `Memory::read` and
/// // `Memory::write` methods.
/// // An error is returned if the copy did not succeed.
/// fn safe_examples(mem: Memory, store: &mut Store<()>) -> Result<(), MemoryAccessError> {
///     let offset = 5;
///     mem.write(&mut *store, offset, b"hello")?;
///     let mut buffer = [0u8; 5];
///     mem.read(&store, offset, &mut buffer)?;
///     assert_eq!(b"hello", &buffer);
///
///     // Note that while this is safe care must be taken because the indexing
///     // here may panic if the memory isn't large enough.
///     assert_eq!(&mem.data(&store)[offset..offset + 5], b"hello");
///     mem.data_mut(&mut *store)[offset..offset + 5].copy_from_slice(b"bye!!");
///
///     Ok(())
/// }
/// ```
///
/// It's worth also, however, covering some examples of **incorrect**,
/// **unsafe** usages of `Memory`. Do not do these things!
///
/// ```rust
/// use wasmtime::{Memory, Result, Store};
///
/// // NOTE: All code in this function is not safe to execute and may cause
/// // segfaults/undefined behavior at runtime. Do not copy/paste these examples
/// // into production code!
/// unsafe fn unsafe_examples(mem: Memory, store: &mut Store<()>) -> Result<()> {
///     // First and foremost, any borrow can be invalidated at any time via the
///     // `Memory::grow` function. This can relocate memory which causes any
///     // previous pointer to be possibly invalid now.
///     unsafe {
///         let pointer: &u8 = &*mem.data_ptr(&store);
///         mem.grow(&mut *store, 1)?; // invalidates `pointer`!
///         // println!("{}", *pointer); // FATAL: use-after-free
///     }
///
///     // Note that the use-after-free also applies to slices, whether they're
///     // slices of bytes or strings.
///     unsafe {
///         let mem_slice = std::slice::from_raw_parts(
///             mem.data_ptr(&store),
///             mem.data_size(&store),
///         );
///         let slice: &[u8] = &mem_slice[0x100..0x102];
///         mem.grow(&mut *store, 1)?; // invalidates `slice`!
///         // println!("{:?}", slice); // FATAL: use-after-free
///     }
///
///     // The `Memory` type may be stored in other locations, so if you hand
///     // off access to the `Store` then those locations may also call
///     // `Memory::grow` or similar, so it's not enough to just audit code for
///     // calls to `Memory::grow`.
///     unsafe {
///         let pointer: &u8 = &*mem.data_ptr(&store);
///         some_other_function(store); // may invalidate `pointer` through use of `store`
///         // println!("{:?}", pointer); // FATAL: maybe a use-after-free
///     }
///
///     // An especially subtle aspect of accessing a wasm instance's memory is
///     // that you need to be extremely careful about aliasing. Anyone at any
///     // time can call `data_unchecked()` or `data_unchecked_mut()`, which
///     // means you can easily have aliasing mutable references:
///     unsafe {
///         let ref1: &u8 = &*mem.data_ptr(&store).add(0x100);
///         let ref2: &mut u8 = &mut *mem.data_ptr(&store).add(0x100);
///         // *ref2 = *ref1; // FATAL: violates Rust's aliasing rules
///     }
///
///     Ok(())
/// }
/// # fn some_other_function(store: &mut Store<()>) {}
/// ```
///
/// Overall there's some general rules of thumb when unsafely working with
/// `Memory` and getting raw pointers inside of it:
///
/// * If you never have a "long lived" pointer into memory, you're likely in the
///   clear. Care still needs to be taken in threaded scenarios or when/where
///   data is read, but you'll be shielded from many classes of issues.
/// * Long-lived pointers must always respect Rust'a aliasing rules. It's ok for
///   shared borrows to overlap with each other, but mutable borrows must
///   overlap with nothing.
/// * Long-lived pointers are only valid if they're not invalidated for their
///   lifetime. This means that [`Store`](crate::Store) isn't used to reenter
///   wasm or the memory itself is never grown or otherwise modified/aliased.
///
/// At this point it's worth reiterating again that unsafely working with
/// `Memory` is pretty tricky and not recommended! It's highly recommended to
/// use the safe methods to interact with [`Memory`] whenever possible.
///
/// ## `Memory` Safety and Threads
///
/// Currently the `wasmtime` crate does not implement the wasm threads proposal,
/// but it is planned to do so. It may be interesting to readers to see how this
/// affects memory safety and what was previously just discussed as well.
///
/// Once threads are added into the mix, all of the above rules still apply.
/// There's an additional consideration that all reads and writes can happen
/// concurrently, though. This effectively means that any borrow into wasm
/// memory are virtually never safe to have.
///
/// Mutable pointers are fundamentally unsafe to have in a concurrent scenario
/// in the face of arbitrary wasm code. Only if you dynamically know for sure
/// that wasm won't access a region would it be safe to construct a mutable
/// pointer. Additionally even shared pointers are largely unsafe because their
/// underlying contents may change, so unless `UnsafeCell` in one form or
/// another is used everywhere there's no safety.
///
/// One important point about concurrency is that while [`Memory::grow`] can
/// happen concurrently it will never relocate the base pointer. Shared
/// memories must always have a maximum size and they will be preallocated such
/// that growth will never relocate the base pointer. The current size of the
/// memory may still change over time though.
///
/// Overall the general rule of thumb for shared memories is that you must
/// atomically read and write everything. Nothing can be borrowed and everything
/// must be eagerly copied out. This means that [`Memory::data`] and
/// [`Memory::data_mut`] won't work in the future (they'll probably return an
/// error) for shared memories when they're implemented. When possible it's
/// recommended to use [`Memory::read`] and [`Memory::write`] which will still
/// be provided.
#[derive(Copy, Clone, Debug)]
#[repr(C)] // here for the C API
pub struct Memory {
    /// The internal store instance that this memory belongs to.
    instance: StoreInstanceId,
    /// The index of the memory, within `instance` above, that this memory
    /// refers to.
    index: DefinedMemoryIndex,
}

// Double-check that the C representation in `extern.h` matches our in-Rust
// representation here in terms of size/alignment/etc.
const _: () = {
    #[repr(C)]
    struct Tmp(u64, u32);
    #[repr(C)]
    struct C(Tmp, u32);
    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Memory>());
    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Memory>());
    assert!(core::mem::offset_of!(Memory, instance) == 0);
};

impl Memory {
    /// Creates a new WebAssembly memory given the configuration of `ty`.
    ///
    /// The `store` argument will be the owner of the returned [`Memory`]. All
    /// WebAssembly memory is initialized to zero.
    ///
    /// # Panics
    ///
    /// This function will panic if the [`Store`](`crate::Store`) has a
    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
    /// [`Store::limiter_async`](`crate::Store::limiter_async`)). When
    /// using an async resource limiter, use [`Memory::new_async`] instead.
    ///
    /// # Examples
    ///
    /// ```
    /// # use wasmtime::*;
    /// # fn main() -> Result<()> {
    /// let engine = Engine::default();
    /// let mut store = Store::new(&engine, ());
    ///
    /// let memory_ty = MemoryType::new(1, None)?;
    /// let memory = Memory::new(&mut store, memory_ty)?;
    ///
    /// let module = Module::new(&engine, "(module (memory (import \"\" \"\") 1))")?;
    /// let instance = Instance::new(&mut store, &module, &[memory.into()])?;
    /// // ...
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn new(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
        let (mut limiter, store) = store
            .as_context_mut()
            .0
            .validate_sync_resource_limiter_and_store_opaque()?;
        vm::assert_ready(Self::_new(store, limiter.as_mut(), ty))
    }

    /// Async variant of [`Memory::new`]. You must use this variant with
    /// [`Store`](`crate::Store`)s which have a
    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
    ///
    /// # Panics
    ///
    /// This function will panic when used with a non-async
    /// [`Store`](`crate::Store`).
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    #[cfg(feature = "async")]
    pub async fn new_async(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {
        let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();
        Self::_new(store, limiter.as_mut(), ty).await
    }

    /// Helper function for attaching the memory to a "frankenstein" instance
    async fn _new(
        store: &mut StoreOpaque,
        limiter: Option<&mut StoreResourceLimiter<'_>>,
        ty: MemoryType,
    ) -> Result<Memory> {
        if ty.is_shared() {
            bail!("shared memories must be created through `SharedMemory`")
        }
        store.bump_memory_count()?;
        Ok(generate_memory_export(store, limiter, &ty, None)
            .await?
            .unshared()
            .unwrap())
    }

    /// Returns the underlying type of this memory.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use wasmtime::*;
    /// # fn main() -> Result<()> {
    /// let engine = Engine::default();
    /// let mut store = Store::new(&engine, ());
    /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1))")?;
    /// let instance = Instance::new(&mut store, &module, &[])?;
    /// let memory = instance.get_memory(&mut store, "mem").unwrap();
    /// let ty = memory.ty(&store);
    /// assert_eq!(ty.minimum(), 1);
    /// # Ok(())
    /// # }
    /// ```
    pub fn ty(&self, store: impl AsContext) -> MemoryType {
        let store = store.as_context();
        MemoryType::from_wasmtime_memory(self.wasmtime_ty(store.0))
    }

    /// Safely reads memory contents at the given offset into a buffer.
    ///
    /// The entire buffer will be filled.
    ///
    /// If `offset + buffer.len()` exceed the current memory capacity, then the
    /// buffer is left untouched and a [`MemoryAccessError`] is returned.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn read(
        &self,
        store: impl AsContext,
        offset: usize,
        buffer: &mut [u8],
    ) -> Result<(), MemoryAccessError> {
        let store = store.as_context();
        let slice = self
            .data(&store)
            .get(offset..)
            .and_then(|s| s.get(..buffer.len()))
            .ok_or(MemoryAccessError { _private: () })?;
        buffer.copy_from_slice(slice);
        Ok(())
    }

    /// Safely writes contents of a buffer to this memory at the given offset.
    ///
    /// If the `offset + buffer.len()` exceeds the current memory capacity, then
    /// none of the buffer is written to memory and a [`MemoryAccessError`] is
    /// returned.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn write(
        &self,
        mut store: impl AsContextMut,
        offset: usize,
        buffer: &[u8],
    ) -> Result<(), MemoryAccessError> {
        let mut context = store.as_context_mut();
        self.data_mut(&mut context)
            .get_mut(offset..)
            .and_then(|s| s.get_mut(..buffer.len()))
            .ok_or(MemoryAccessError { _private: () })?
            .copy_from_slice(buffer);
        Ok(())
    }

    /// Returns this memory as a native Rust slice.
    ///
    /// Note that this method will consider the entire store context provided as
    /// borrowed for the duration of the lifetime of the returned slice.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn data<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a [u8] {
        unsafe {
            let store = store.into();
            let definition = store[self.instance].memory(self.index);
            debug_assert!(!self.ty(store).is_shared());
            slice::from_raw_parts(definition.base.as_ptr(), definition.current_length())
        }
    }

    /// Returns this memory as a native Rust mutable slice.
    ///
    /// Note that this method will consider the entire store context provided as
    /// borrowed for the duration of the lifetime of the returned slice.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn data_mut<'a, T: 'static>(
        &self,
        store: impl Into<StoreContextMut<'a, T>>,
    ) -> &'a mut [u8] {
        unsafe {
            let store = store.into();
            let definition = store[self.instance].memory(self.index);
            debug_assert!(!self.ty(store).is_shared());
            slice::from_raw_parts_mut(definition.base.as_ptr(), definition.current_length())
        }
    }

    /// Same as [`Memory::data_mut`], but also returns the `T` from the
    /// [`StoreContextMut`].
    ///
    /// This method can be used when you want to simultaneously work with the
    /// `T` in the store as well as the memory behind this [`Memory`]. Using
    /// [`Memory::data_mut`] would consider the entire store borrowed, whereas
    /// this method allows the Rust compiler to see that the borrow of this
    /// memory and the borrow of `T` are disjoint.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn data_and_store_mut<'a, T: 'static>(
        &self,
        store: impl Into<StoreContextMut<'a, T>>,
    ) -> (&'a mut [u8], &'a mut T) {
        // Note the unsafety here. Our goal is to simultaneously borrow the
        // memory and custom data from `store`, and the store it's connected
        // to. Rust will not let us do that, however, because we must call two
        // separate methods (both of which borrow the whole `store`) and one of
        // our borrows is mutable (the custom data).
        //
        // This operation, however, is safe because these borrows do not overlap
        // and in the process of borrowing them mutability doesn't actually
        // touch anything. This is akin to mutably borrowing two indices in an
        // array, which is safe so long as the indices are separate.
        unsafe {
            let mut store = store.into();
            let data = &mut *(store.data_mut() as *mut T);
            (self.data_mut(store), data)
        }
    }

    /// Returns the base pointer, in the host's address space, that the memory
    /// is located at.
    ///
    /// For more information and examples see the documentation on the
    /// [`Memory`] type.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn data_ptr(&self, store: impl AsContext) -> *mut u8 {
        store.as_context()[self.instance]
            .memory(self.index)
            .base
            .as_ptr()
    }

    /// Returns the byte length of this memory.
    ///
    /// WebAssembly memories are made up of a whole number of pages, so the byte
    /// size returned will always be a multiple of this memory's page size. Note
    /// that different Wasm memories may have different page sizes. You can get
    /// a memory's page size via the [`Memory::page_size`] method.
    ///
    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
    /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
    /// into a page size of `1`. Future extensions might allow any power of two
    /// as a page size.
    ///
    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    ///
    /// For more information and examples see the documentation on the
    /// [`Memory`] type.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn data_size(&self, store: impl AsContext) -> usize {
        self.internal_data_size(store.as_context().0)
    }

    pub(crate) fn internal_data_size(&self, store: &StoreOpaque) -> usize {
        store[self.instance].memory(self.index).current_length()
    }

    /// Returns the size, in units of pages, of this Wasm memory.
    ///
    /// WebAssembly memories are made up of a whole number of pages, so the byte
    /// size returned will always be a multiple of this memory's page size. Note
    /// that different Wasm memories may have different page sizes. You can get
    /// a memory's page size via the [`Memory::page_size`] method.
    ///
    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
    /// `65536`) but [the custom-page-sizes proposal] allows a memory to opt
    /// into a page size of `1`. Future extensions might allow any power of two
    /// as a page size.
    ///
    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    pub fn size(&self, store: impl AsContext) -> u64 {
        self.internal_size(store.as_context().0)
    }

    pub(crate) fn internal_size(&self, store: &StoreOpaque) -> u64 {
        let byte_size = self.internal_data_size(store);
        let page_size = usize::try_from(self._page_size(store)).unwrap();
        u64::try_from(byte_size / page_size).unwrap()
    }

    /// Returns the size of a page, in bytes, for this memory.
    ///
    /// WebAssembly memories are made up of a whole number of pages, so the byte
    /// size (as returned by [`Memory::data_size`]) will always be a multiple of
    /// their page size. Different Wasm memories may have different page sizes.
    ///
    /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
    /// but [the custom-page-sizes proposal] allows opting into a page size of
    /// `1`. Future extensions might allow any power of two as a page size.
    ///
    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    pub fn page_size(&self, store: impl AsContext) -> u64 {
        self._page_size(store.as_context().0)
    }

    pub(crate) fn _page_size(&self, store: &StoreOpaque) -> u64 {
        self.wasmtime_ty(store).page_size()
    }

    /// Returns the log2 of this memory's page size, in bytes.
    ///
    /// WebAssembly memories are made up of a whole number of pages, so the byte
    /// size (as returned by [`Memory::data_size`]) will always be a multiple of
    /// their page size. Different Wasm memories may have different page sizes.
    ///
    /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or
    /// `65536`) but [the custom-page-sizes proposal] allows opting into a page
    /// size of `1`. Future extensions might allow any power of two as a page
    /// size.
    ///
    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    pub fn page_size_log2(&self, store: impl AsContext) -> u8 {
        self._page_size_log2(store.as_context().0)
    }

    pub(crate) fn _page_size_log2(&self, store: &StoreOpaque) -> u8 {
        self.wasmtime_ty(store).page_size_log2
    }

    /// Grows this WebAssembly memory by `delta` pages.
    ///
    /// This will attempt to add `delta` more pages of memory on to the end of
    /// this `Memory` instance. If successful this may relocate the memory and
    /// cause [`Memory::data_ptr`] to return a new value. Additionally any
    /// unsafely constructed slices into this memory may no longer be valid.
    ///
    /// On success returns the number of pages this memory previously had
    /// before the growth succeeded.
    ///
    /// Note that, by default, a WebAssembly memory's page size is 64KiB (aka
    /// 65536 or 2<sup>16</sup>). The [custom-page-sizes proposal] allows Wasm
    /// memories to opt into a page size of one byte (and this may be further
    /// relaxed to any power of two in a future extension).
    ///
    /// [custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    ///
    /// # Errors
    ///
    /// Returns an error if memory could not be grown, for example if it exceeds
    /// the maximum limits of this memory. A
    /// [`ResourceLimiter`](crate::ResourceLimiter) is another example of
    /// preventing a memory to grow.
    ///
    /// This function will return an error if the [`Store`](`crate::Store`) has
    /// a [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`) (see also:
    /// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an
    /// async resource limiter, use [`Memory::grow_async`] instead.
    ///
    /// This function will handle out-of-memory conditions and report an error
    /// in such cases, see the `OutOfMemory` type's documentation for details on
    /// Wasmtime's out-of-memory handling. Note that the `OutOfMemory` type may
    /// not literally be returned for detecting this condition.
    ///
    /// # Panics
    ///
    /// Panics if this memory doesn't belong to `store`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use wasmtime::*;
    /// # fn main() -> Result<()> {
    /// let engine = Engine::default();
    /// let mut store = Store::new(&engine, ());
    /// let module = Module::new(&engine, "(module (memory (export \"mem\") 1 2))")?;
    /// let instance = Instance::new(&mut store, &module, &[])?;
    /// let memory = instance.get_memory(&mut store, "mem").unwrap();
    ///
    /// assert_eq!(memory.size(&store), 1);
    /// assert_eq!(memory.grow(&mut store, 1)?, 1);
    /// assert_eq!(memory.size(&store), 2);
    /// assert!(memory.grow(&mut store, 1).is_err());
    /// assert_eq!(memory.size(&store), 2);
    /// assert_eq!(memory.grow(&mut store, 0)?, 2);
    /// # Ok(())
    /// # }
    /// ```
    pub fn grow(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
        let store = store.as_context_mut().0;
        let (mut limiter, store) = store.validate_sync_resource_limiter_and_store_opaque()?;
        vm::assert_ready(self._grow(store, limiter.as_mut(), delta))
    }

    /// Async variant of [`Memory::grow`]. Required when using a
    /// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).
    ///
    /// # Panics
    ///
    /// This function will panic when used with a non-async
    /// [`Store`](`crate::Store`).
    ///
    /// # Errors
    ///
    /// This function will return errors for the same reasons as
    /// [`Memory::grow`].
    #[cfg(feature = "async")]
    pub async fn grow_async(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {
        let store = store.as_context_mut();
        let (mut limiter, store) = store.0.resource_limiter_and_store_opaque();
        self._grow(store, limiter.as_mut(), delta).await
    }

    async fn _grow(
        &self,
        store: &mut StoreOpaque,
        limiter: Option<&mut StoreResourceLimiter<'_>>,
        delta: u64,
    ) -> Result<u64> {
        let result = self
            .instance
            .get_mut(store)
            .memory_grow(limiter, self.index, delta)
            .await?;
        match result {
            Some(size) => {
                let page_size = self.wasmtime_ty(store).page_size();
                Ok(u64::try_from(size).unwrap() / page_size)
            }
            None => bail!("failed to grow memory by `{delta}`"),
        }
    }

    /// Creates a new memory from its raw component parts.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the memory pointed to by `instance` and
    /// `index` is not a shared memory. For that `SharedMemory` must be used
    /// instead.
    pub(crate) unsafe fn from_raw(instance: StoreInstanceId, index: DefinedMemoryIndex) -> Memory {
        Memory { instance, index }
    }

    pub(crate) fn wasmtime_ty<'a>(&self, store: &'a StoreOpaque) -> &'a wasmtime_environ::Memory {
        let module = store[self.instance].env_module();
        let index = module.memory_index(self.index);
        &module.memories[index]
    }

    pub(crate) fn vmimport(&self, store: &StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
        store[self.instance].get_defined_memory_vmimport(self.index)
    }

    pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
        store.id() == self.instance.store_id()
    }

    /// Returns a stable identifier for this memory within its store.
    ///
    /// This allows distinguishing memories when introspecting them
    /// e.g. via debug APIs.
    #[cfg(feature = "debug")]
    pub fn debug_index_in_store(&self) -> u64 {
        u64::from(self.instance.instance().as_u32()) << 32 | u64::from(self.index.as_u32())
    }

    /// Get a stable hash key for this memory.
    ///
    /// Even if the same underlying memory definition is added to the
    /// `StoreData` multiple times and becomes multiple `wasmtime::Memory`s,
    /// this hash key will be consistent across all of these memories.
    #[cfg(feature = "coredump")]
    pub(crate) fn hash_key(&self, store: &StoreOpaque) -> impl core::hash::Hash + Eq + use<> {
        store[self.instance].memory_ptr(self.index).as_ptr().addr()
    }
}

/// A linear memory. This trait provides an interface for raw memory buffers
/// which are used by wasmtime, e.g. inside ['Memory']. Such buffers are in
/// principle not thread safe. By implementing this trait together with
/// MemoryCreator, one can supply wasmtime with custom allocated host managed
/// memory.
///
/// Note that this is a relatively advanced feature and it is recommended to be
/// familiar with wasmtime runtime code to use it.
///
/// In the following, `minimum`, `reserved_size_in_bytes`, and `guard_size_in_bytes` arguments are given to a
/// [`MemoryCreator::new_memory`] implementation.
///
/// # Safety
///
/// Wasmtime's compiled code and runtime rely on the following invariants for memory safety.
/// Note that while we strive to be thorough in this documentation, we do not guarantee that the
/// following points are exhaustive.
/// When using a custom memory backend in a security-sensitive context auditing just the external
/// implementation of this trait is not sufficient.
///
/// - **Valid region.** From creation until the memory is dropped, the first
/// [`byte_size`] bytes starting at the [`as_ptr`]
/// memory location must be allocated, initialized, readable, and writeable.
/// The pointer must be non-null.
/// Nothing other than Wasmtime may read, write, unmap, or otherwise modify this region while the
/// memory is in use by Wasmtime.
/// If the memory moves (although see conditions on stability below), the previous region is no
/// longer in use by Wasmtime.
/// Moreover, be aware that Wasmtime currently has a soundness hole for shared memory,
/// as multiple threads may access the same slice of memory mutably at the same time (aliasing) (see
/// [issue #4203](https://github.com/bytecodealliance/wasmtime/issues/4203)).
///
/// - **Size.** [`byte_size`] must be at least `minimum` after creation
/// and at least `new_size` after a successful call to [`grow_to`],
/// and it must never decrease.
///
/// - **Base pointer stability.** A call to [`as_ptr`] must return the same
/// address until the next successful call to [`grow_to`].
/// Moreover, a successful [`grow_to(new_size)`][`grow_to`] call where `new_size` is at most the [`byte_capacity`](LinearMemory::byte_capacity)
/// reported before the call must not change the result of [`as_ptr`].
/// If static memory is forced (e.g. when using shared memory or when [`Config::memory_may_move`](crate::Config::memory_may_move) is disabled), Wasmtime will never ask the memory to grow beyond its [`byte_capacity`].
///
/// - **Base pointer alignment.** The base pointer returned by [`as_ptr`] must always be 8-byte aligned.
/// Moreover, if `guard_size_in_bytes` is non-zero, or `reserved_size_in_bytes` is `Some` and non-zero, then [`as_ptr`] must be
/// aligned to the host page size at all times.
///
/// - **Inaccessible region.** If: `guard_size_in_bytes` is non-zero, or `reserved_size_in_bytes` is `Some` and non-zero;
/// then every byte from `as_ptr() + byte_size()`, rounded up to the next host page boundary, up to
/// `as_ptr() + max(reserved_size_in_bytes, byte_size()) + guard_size_in_bytes` must be
/// inaccessible, so that any access to it faults. This must hold at all times, including after growth.
///
/// Additionally, observe the safety requirements when the memory is accessed, as explained in [`Memory`].
///
/// # Correctness
///
/// The following constraints do not cause memory safety issues, but break WebAssembly semantics,
/// or expose potentially unwanted data to WebAssembly programs:
///
/// - [`byte_size`] should be exactly `minimum` after creation and exactly `new_size` after a
/// successful call to [`grow_to(new_size)`][`grow_to`]. Wasmtime only requests sizes that are
/// multiples of the Wasm page size.
///
/// - The memory's contents must be zeroed at creation, and bytes made accessible by [`grow_to`] must
/// be zeroed.
///
/// - If [`init_from_image`] returns `Ok(true)`, then the bytes at [`MemoryImage::linear_memory_offset`]
/// must equal the image and all other bytes must be zero.
///
/// [`grow_to`]: LinearMemory::grow_to
/// [`byte_size`]: LinearMemory::byte_size
/// [`as_ptr`]: LinearMemory::as_ptr
/// [`byte_capacity`]: LinearMemory::byte_capacity
/// [`init_from_image`]: LinearMemory::init_from_image
pub unsafe trait LinearMemory: Any + Send + Sync {
    /// Returns the number of allocated bytes which are accessible at this time.
    fn byte_size(&self) -> usize;

    /// Returns byte capacity of this linear memory's current allocation.
    ///
    /// Growth up to this value should not relocate the linear memory base
    /// pointer.
    fn byte_capacity(&self) -> usize;

    /// Grows this memory to have the `new_size`, in bytes, specified.
    ///
    /// Returns `Err` if memory can't be grown by the specified amount
    /// of bytes. The error may be downcastable to `std::io::Error`.
    /// Returns `Ok` if memory was grown successfully.
    fn grow_to(&mut self, new_size: usize) -> Result<()>;

    /// Return the allocated memory as a mutable pointer to u8.
    fn as_ptr(&self) -> *mut u8;

    /// Optionally initializes this memory's contents from a copy-on-write
    /// [`MemoryImage`].
    ///
    /// When [copy-on-write memory initialization][cow_config] is enabled and a
    /// module's data segments for this memory can be represented as an image,
    /// Wasmtime calls this method once, right after the memory is created
    /// and before anything else reads or writes it.
    ///
    /// If the function succeeds with `false`, the runtime assumes the memory was not initialized.
    /// It then fully copies the module's data segments into the memory region.
    /// This is always correct and is essentially equivalent to CoW being disabled.
    ///
    /// If the function succeeds with `true`, the runtime assumes the memory's contents match `image` exactly.
    /// The bytes of the image must start at [`MemoryImage::linear_memory_offset`] and all other bytes must be zero.
    ///
    /// ## Shortcut for memory maps
    ///
    /// [`MemoryImage`] exposes a shortcut, [`MemoryImage::map_at`], which allows an implementation
    /// backed by a memory map to replace a portion of its mapping with the pages of the image.
    /// Consult that function's documentation for safety notes.
    ///
    /// Returning an error causes instantiation to fail with that error.
    ///
    /// [cow_config]: crate::Config::memory_init_cow
    fn init_from_image(&mut self, image: &MemoryImage) -> Result<bool> {
        let _ = image;
        Ok(false)
    }
}

/// A copy-on-write image of the initial contents of a linear memory.
///
/// When [`Config::memory_init_cow`](crate::Config::memory_init_cow) is enabled
/// Wasmtime prepares, where possible, an image of a module's data segments for
/// each of its linear memories that can be mapped into memory copy-on-write
/// instead of being copied byte-by-byte. Such images are handed to
/// [`LinearMemory::init_from_image`] for the specific memory implementation to map into its
/// underlying representation.
///
/// An image covers [`len()`](MemoryImage::len) bytes of the linear memory starting at
/// [`linear_memory_offset()`](MemoryImage::linear_memory_offset).
/// Both values are multiples of the host page size, and the image always lies within
/// the minimum size of the memory it was created for.
/// All other bytes are expected to be zero.
///
/// Cloning a `MemoryImage` is cheap and keeps the underlying image alive.
#[derive(Clone)]
pub struct MemoryImage {
    image: Arc<vm::MemoryImage>,
}

impl MemoryImage {
    pub(crate) fn new(image: Arc<vm::MemoryImage>) -> MemoryImage {
        MemoryImage { image }
    }

    /// This is a convenience method for the internal `MmapMemory` to access the underlying image
    /// directly and use its [`map_at`](vm::MemoryImage::map_at) function.
    #[cfg(has_virtual_memory)]
    pub(crate) fn vm(&self) -> &vm::MemoryImage {
        &self.image
    }

    /// Returns the offset, in bytes, within linear memory where this image
    /// starts.
    ///
    /// This is guaranteed to be a multiple of the host page size.
    pub fn linear_memory_offset(&self) -> usize {
        self.image.linear_memory_offset()
    }

    /// Returns the length, in bytes, of this image.
    ///
    /// This is guaranteed to be a multiple of the host page size.
    pub fn len(&self) -> usize {
        self.image.len()
    }

    /// Returns whether this image is empty (length equal to zero).
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Returns the bytes of this image.
    ///
    /// The returned slice is [`len()`](MemoryImage::len) bytes long and holds
    /// the initial contents of linear memory starting at
    /// [`linear_memory_offset()`](MemoryImage::linear_memory_offset). All
    /// bytes of the memory outside of that range are initially zero.
    pub fn data(&self) -> &[u8] {
        self.image.data()
    }

    /// Maps this image copy-on-write into the linear memory starting at
    /// `base`.
    ///
    /// The bytes `base + linear_memory_offset()` up to
    /// `base + linear_memory_offset() + len()` are replaced with a private,
    /// readable and writable copy-on-write mapping of the image. Nothing
    /// outside of that range is modified.
    ///
    /// Returns an error if `base` is not aligned to the host page size or if
    /// the underlying mapping operation fails.
    ///
    /// # Safety
    ///
    /// The caller must exclusively own the virtual memory range being mapped
    /// over, nothing may hold references into it, and it must be valid for
    /// its pages to be replaced by a new mapping (for example by `mmap` with
    /// `MAP_FIXED` on Unix). Any previous contents and memory protections of
    /// that range are lost. The mapping lives until the range is unmapped or
    /// mapped over again by its owner. In particular, the runtime does not unmap the image by itself.
    /// The owner of the virtual memory range must clean it up after usage.
    ///
    /// The typical usage is owning a memory-mapped region and requesting the image to be mapped
    /// into a subrange of that mapping. Unmapping the entire region at the end of the memory's
    /// lifetime takes care of the cleanup.
    pub unsafe fn map_at(&self, base: *mut u8) -> Result<()> {
        // SAFETY: forwarded to the caller.
        unsafe { self.image.map_at_ptr(base) }
    }
}

impl fmt::Debug for MemoryImage {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("MemoryImage")
            .field("linear_memory_offset", &self.linear_memory_offset())
            .field("len", &self.len())
            .finish_non_exhaustive()
    }
}

impl PartialEq for MemoryImage {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.image, &other.image)
    }
}

impl Eq for MemoryImage {}

impl core::hash::Hash for MemoryImage {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        core::ptr::hash(Arc::as_ptr(&self.image), state)
    }
}

/// A memory creator. Can be used to provide a memory creator
/// to wasmtime which supplies host managed memory.
///
/// # Safety
///
/// This trait is unsafe, as the memory safety depends on proper implementation
/// of memory management. Memories created by the MemoryCreator should always be
/// treated as owned by wasmtime instance, and any modification of them outside
/// of wasmtime invoked routines is unsafe and may lead to corruption.
///
/// Note that this is a relatively advanced feature and it is recommended to be
/// familiar with Wasmtime runtime code to use it.
pub unsafe trait MemoryCreator: Send + Sync {
    /// Create a new [`LinearMemory`] object from the specified parameters.
    ///
    /// The returned memory must satisfy all of the properties of the [`MemoryRequest`]
    /// and be zero filled.
    fn new_memory(&self, request: &MemoryRequest<'_>) -> Result<Box<dyn LinearMemory>>;
}

/// The kind of memory that [`MemoryCreator`] is asked to create.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum MemoryKind {
    /// A standard WebAssembly linear memory (module or host).
    LinearMemory,
    /// The memory backing a store's GC heap.
    ///
    /// It differs from standard linear memory:
    /// - It is created lazily, at most once per store: when a module that needs a GC heap is
    ///   instantiated or when the first GC object is allocated. This might happen in the middle of
    ///   execution of WebAssembly code.
    /// - It grows as GC objects are allocated, independently of `memory.grow`.
    /// - Its contents are Wasmtime's internal representation of GC objects, not data of the guest
    ///   program. They are only meaningful to the store that created the GC heap, so they should not
    ///   be shared, persisted, copied to other memories, etc.
    GcHeap,
}

impl From<wasmtime_environ::MemoryKind> for MemoryKind {
    fn from(value: wasmtime_environ::MemoryKind) -> Self {
        match value {
            wasmtime_environ::MemoryKind::LinearMemory => Self::LinearMemory,
            wasmtime_environ::MemoryKind::GcHeap => Self::GcHeap,
        }
    }
}

/// A request to a [`MemoryCreator::new_memory`].
pub struct MemoryRequest<'a> {
    ty: &'a wasmtime_environ::Memory,
    tunables: &'a MemoryTunables<'a>,
    minimum: usize,
    maximum: Option<usize>,
}

impl<'a> MemoryRequest<'a> {
    pub(crate) fn new(
        ty: &'a wasmtime_environ::Memory,
        tunables: &'a MemoryTunables<'a>,
        minimum: usize,
        maximum: Option<usize>,
    ) -> Self {
        Self {
            ty,
            tunables,
            minimum,
            maximum,
        }
    }

    /// The type of memory being created. Indicates
    /// both the minimum and maximum size, in wasm pages. The minimum and
    /// maximum sizes, in bytes, are also specified as [`minimum`](Self::minimum) and [`maximum`](Self::maximum)
    /// to avoid integer conversion if desired.
    pub fn ty(&self) -> MemoryType {
        MemoryType::from_wasmtime_memory(self.ty)
    }

    /// Minimum size of the memory in bytes.
    /// Same as the minimum of [`ty`](Self::ty), but in bytes.
    pub fn minimum(&self) -> usize {
        self.minimum
    }

    /// Limit on the maximum size of the memory in bytes, if any.
    /// Same as the maximum of [`ty`](Self::ty), but in bytes.
    pub fn maximum(&self) -> Option<usize> {
        self.maximum
    }

    /// Indicates the expected size of the reservation that is to be made for this memory.
    /// The implementation must reserve this many bytes for the memory's allocation, plus the guard
    /// size at the end. Note that this reservation need only be a virtual
    /// memory reservation, physical memory does not need to be allocated
    /// immediately.
    ///
    /// If this value is not zero, [`grow_to`](LinearMemory::grow_to) should never move the base pointer and
    /// the maximum size of [`ty`](Self::ty) is guaranteed to fit within `reserved_size_in_bytes`.
    ///
    /// This value is tuned from the various [`Config`](crate::Config) methods about
    /// memory sizes/guards. It is guaranteed to be a multiple of the system page size.
    pub fn reserved_size_in_bytes(&self) -> usize {
        usize::try_from(self.tunables.reservation()).unwrap()
    }

    /// Indicates how many bytes of space after the memory allocation is expected to be unmapped. JIT code will
    /// elide bounds checks based on the `guard_size_in_bytes` provided, so for
    /// JIT code to work correctly the memory returned will need to be properly
    /// guarded with `guard_size_in_bytes` bytes left unmapped after the base
    /// allocation.
    ///
    /// This value is tuned from the various [`Config`](crate::Config) methods about
    /// memory sizes/guards. It is guaranteed to be a multiple of the system page size.
    pub fn guard_size_in_bytes(&self) -> usize {
        usize::try_from(self.tunables.guard_size()).unwrap()
    }

    /// What kind of memory is requested.
    pub fn kind(&self) -> MemoryKind {
        self.tunables.kind().into()
    }

    /// Internal parameter: detailed internal representation of the memory being created.
    pub(crate) fn wasmtime_memory(&self) -> &'a wasmtime_environ::Memory {
        self.ty
    }

    /// Internal parameter: all the tunables, including those not exposed to the public API.
    pub(crate) fn tunables(&self) -> &'a MemoryTunables<'a> {
        self.tunables
    }
}

impl fmt::Debug for MemoryRequest<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("MemoryRequest")
            .field("ty", &self.ty())
            .field("minimum", &self.minimum)
            .field("maximum", &self.maximum)
            .field("reserved_size_in_bytes", &self.reserved_size_in_bytes())
            .field("guard_size_in_bytes", &self.guard_size_in_bytes())
            .field("kind", &self.kind())
            .finish()
    }
}

/// A constructor for externally-created shared memory.
///
/// The [threads proposal] adds the concept of "shared memory" to WebAssembly.
/// This is much the same as a Wasm linear memory (i.e., [`Memory`]), but can be
/// used concurrently by multiple agents. Because these agents may execute in
/// different threads, [`SharedMemory`] must be thread-safe.
///
/// When the [threads proposal is enabled](crate::Config::wasm_threads) and the
/// [the creation of shared memories is enabled](crate::Config::shared_memory),
/// there are multiple ways to construct shared memory:
///  1. for imported shared memory, e.g., `(import "env" "memory" (memory 1 1
///     shared))`, the user must supply a [`SharedMemory`] with the
///     externally-created memory as an import to the instance--e.g.,
///     `shared_memory.into()`.
///  2. for private or exported shared memory, e.g., `(export "env" "memory"
///     (memory 1 1 shared))`, Wasmtime will create the memory internally during
///     instantiation--access using `Instance::get_shared_memory()`.
///
/// [threads proposal]:
///     https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md
///
/// # Examples
///
/// ```
/// # use wasmtime::*;
/// # fn main() -> Result<()> {
/// let mut config = Config::new();
/// config.wasm_threads(true);
/// config.shared_memory(true);
/// # if Engine::new(&config).is_err() { return Ok(()); }
/// let engine = Engine::new(&config)?;
/// let mut store = Store::new(&engine, ());
///
/// let shared_memory = SharedMemory::new(&engine, MemoryType::shared(1, 2)?)?;
/// let module = Module::new(&engine, r#"(module (memory (import "" "") 1 2 shared))"#)?;
/// let instance = Instance::new(&mut store, &module, &[shared_memory.into()])?;
/// // ...
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct SharedMemory {
    vm: crate::runtime::vm::SharedMemory,
    engine: Engine,
}

impl SharedMemory {
    /// Construct a [`SharedMemory`] by providing both the `minimum` and
    /// `maximum` number of 64K-sized pages. This call allocates the necessary
    /// pages on the system.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    #[cfg(feature = "threads")]
    pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self> {
        if !ty.is_shared() {
            bail!("shared memory must have the `shared` flag enabled on its memory type")
        }
        debug_assert!(ty.maximum().is_some());

        let ty = ty.wasmtime_memory();
        let memory = crate::runtime::vm::SharedMemory::new(engine, ty)?;

        Ok(Self {
            vm: memory,
            engine: engine.clone(),
        })
    }

    /// Return the type of the shared memory.
    pub fn ty(&self) -> MemoryType {
        MemoryType::from_wasmtime_memory(&self.vm.ty())
    }

    /// Returns the size, in WebAssembly pages, of this wasm memory.
    pub fn size(&self) -> u64 {
        let byte_size = u64::try_from(self.data_size()).unwrap();
        let page_size = self.page_size();
        byte_size / page_size
    }

    /// Returns the size of a page, in bytes, for this memory.
    ///
    /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`)
    /// but [the custom-page-sizes proposal] allows opting into a page size of
    /// `1`. Future extensions might allow any power of two as a page size.
    ///
    /// [the custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
    pub fn page_size(&self) -> u64 {
        self.ty().page_size()
    }

    /// Returns the byte length of this memory.
    ///
    /// The returned value will be a multiple of the wasm page size, 64k.
    ///
    /// For more information and examples see the documentation on the
    /// [`Memory`] type.
    pub fn data_size(&self) -> usize {
        self.vm.byte_size()
    }

    /// Return access to the available portion of the shared memory.
    ///
    /// The slice returned represents the region of accessible memory at the
    /// time that this function was called. The contents of the returned slice
    /// will reflect concurrent modifications happening on other threads.
    ///
    /// # Safety
    ///
    /// The returned slice is valid for the entire duration of the lifetime of
    /// this instance of [`SharedMemory`]. The base pointer of a shared memory
    /// does not change. This [`SharedMemory`] may grow further after this
    /// function has been called, but the slice returned will not grow.
    ///
    /// Concurrent modifications may be happening to the data returned on other
    /// threads. The `UnsafeCell<u8>` represents that safe access to the
    /// contents of the slice is not possible through normal loads and stores.
    ///
    /// The memory returned must be accessed safely through the `Atomic*` types
    /// in the [`std::sync::atomic`] module. Casting to those types must
    /// currently be done unsafely.
    pub fn data(&self) -> &[UnsafeCell<u8>] {
        unsafe {
            let definition = self.vm.vmmemory_ptr().as_ref();
            slice::from_raw_parts(definition.base.as_ptr().cast(), definition.current_length())
        }
    }

    /// Grows this WebAssembly memory by `delta` pages.
    ///
    /// This will attempt to add `delta` more pages of memory on to the end of
    /// this `Memory` instance. If successful this may relocate the memory and
    /// cause [`Memory::data_ptr`] to return a new value. Additionally any
    /// unsafely constructed slices into this memory may no longer be valid.
    ///
    /// On success returns the number of pages this memory previously had
    /// before the growth succeeded.
    ///
    /// # Errors
    ///
    /// This function will return errors for a similar reason as
    /// [`Memory::grow`].
    pub fn grow(&self, delta: u64) -> Result<u64> {
        match self.vm.grow(delta)? {
            Some((old_size, _new_size)) => {
                // For shared memory, the `VMMemoryDefinition` is updated inside
                // the locked region.
                Ok(u64::try_from(old_size).unwrap() / self.page_size())
            }
            None => bail!("failed to grow memory by `{delta}`"),
        }
    }

    /// Returns a stable identifier for this shared memory when introspecting
    /// it through the debug APIs.
    #[cfg(feature = "debug")]
    pub fn debug_index_in_store(&self) -> u64 {
        u64::try_from(self.vm.vmmemory_ptr().as_ptr().addr()).unwrap()
    }

    /// Equivalent of the WebAssembly `memory.atomic.notify` instruction for
    /// this shared memory.
    ///
    /// This method allows embedders to notify threads blocked on the specified
    /// `addr`, an index into wasm linear memory. Threads could include
    /// wasm threads blocked on a `memory.atomic.wait*` instruction or embedder
    /// threads blocked on [`SharedMemory::atomic_wait32`], for example.
    ///
    /// The `count` argument is the number of threads to wake up.
    ///
    /// This function returns the number of threads awoken.
    ///
    /// # Errors
    ///
    /// This function will return an error if `addr` is not within bounds or
    /// not aligned to a 4-byte boundary.
    pub fn atomic_notify(&self, addr: u64, count: u32) -> Result<u32, Trap> {
        self.vm.atomic_notify(addr, count)
    }

    /// Equivalent of the WebAssembly `memory.atomic.wait32` instruction for
    /// this shared memory.
    ///
    /// This method allows embedders to block the current thread until notified
    /// via the `memory.atomic.notify` instruction or the
    /// [`SharedMemory::atomic_notify`] method, enabling synchronization with
    /// the wasm guest as desired.
    ///
    /// The `expected` argument is the expected 32-bit value to be stored at
    /// the byte address `addr` specified. The `addr` specified is an index
    /// into this linear memory.
    ///
    /// The optional `timeout` argument is the maximum amount of time to block
    /// the current thread. If not specified the thread may sleep indefinitely.
    ///
    /// This function returns one of three possible values:
    ///
    /// * `WaitResult::Ok` - this function, loaded the value at `addr`, found
    ///   it was equal to `expected`, and then blocked (all as one atomic
    ///   operation). The thread was then awoken with a `memory.atomic.notify`
    ///   instruction or the [`SharedMemory::atomic_notify`] method.
    /// * `WaitResult::Mismatch` - the value at `addr` was loaded but was not
    ///   equal to `expected` so the thread did not block and immediately
    ///   returned.
    /// * `WaitResult::TimedOut` - all the steps of `Ok` happened, except this
    ///   thread was woken up due to a timeout.
    ///
    /// This function will not return due to spurious wakeups.
    ///
    /// # Errors
    ///
    /// This function will return an error if `addr` is not within bounds or
    /// not aligned to a 4-byte boundary.
    pub fn atomic_wait32(
        &self,
        addr: u64,
        expected: u32,
        timeout: Option<Duration>,
    ) -> Result<WaitResult, Trap> {
        self.vm.atomic_wait32(addr, expected, timeout)
    }

    /// Equivalent of the WebAssembly `memory.atomic.wait64` instruction for
    /// this shared memory.
    ///
    /// For more information see [`SharedMemory::atomic_wait32`].
    ///
    /// # Errors
    ///
    /// Returns the same error as [`SharedMemory::atomic_wait32`] except that
    /// the specified address must be 8-byte aligned instead of 4-byte aligned.
    pub fn atomic_wait64(
        &self,
        addr: u64,
        expected: u64,
        timeout: Option<Duration>,
    ) -> Result<WaitResult, Trap> {
        self.vm.atomic_wait64(addr, expected, timeout)
    }

    /// Return a reference to the [`Engine`] used to configure the shared
    /// memory.
    pub(crate) fn engine(&self) -> &Engine {
        &self.engine
    }

    /// Construct a single-memory instance to provide a way to import
    /// [`SharedMemory`] into other modules.
    pub(crate) fn vmimport(&self, store: &mut StoreOpaque) -> crate::runtime::vm::VMMemoryImport {
        // Note `vm::assert_ready` shouldn't panic here because this isn't
        // actually allocating any new memory (also no limiter), so resource
        // limiting shouldn't kick in.
        let memory = vm::assert_ready(generate_memory_export(
            store,
            None,
            &self.ty(),
            Some(&self.vm),
        ))
        .unwrap();
        match memory {
            ExportMemory::Unshared(_) => unreachable!(),
            ExportMemory::Shared(_shared, vmimport) => vmimport,
        }
    }

    /// Creates a [`SharedMemory`] from its constituent parts.
    pub(crate) fn from_raw(vm: crate::runtime::vm::SharedMemory, engine: Engine) -> Self {
        SharedMemory { vm, engine }
    }
}

impl fmt::Debug for SharedMemory {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SharedMemory").finish_non_exhaustive()
    }
}

#[cfg(test)]
mod tests {
    use crate::*;

    // Assert that creating a memory via `Memory::new` respects the limits/tunables
    // in `Config`.
    #[test]
    fn respect_tunables() {
        let mut cfg = Config::new();
        cfg.memory_reservation(0).memory_guard_size(0);
        let mut store = Store::new(&Engine::new(&cfg).unwrap(), ());
        let ty = MemoryType::new(1, None).unwrap();
        let mem = Memory::new(&mut store, ty).unwrap();
        let store = store.as_context();
        let tunables = store.engine().tunables();
        assert_eq!(tunables.memory_guard_size, 0);
        assert!(!mem.wasmtime_ty(store.0).can_elide_bounds_check(
            &wasmtime_environ::MemoryTunables::new(
                tunables,
                wasmtime_environ::MemoryKind::LinearMemory,
            ),
            12,
        ));
    }

    #[test]
    fn hash_key_is_stable_across_duplicate_store_data_entries() -> Result<()> {
        let mut store = Store::<()>::default();
        let module = Module::new(
            store.engine(),
            r#"
                (module
                    (memory (export "m") 1 1)
                )
            "#,
        )?;
        let instance = Instance::new(&mut store, &module, &[])?;

        // Each time we `get_memory`, we call `Memory::from_wasmtime` which adds
        // a new entry to `StoreData`, so `g1` and `g2` will have different
        // indices into `StoreData`.
        let m1 = instance.get_memory(&mut store, "m").unwrap();
        let m2 = instance.get_memory(&mut store, "m").unwrap();

        // That said, they really point to the same memory.
        assert_eq!(m1.data(&store)[0], 0);
        assert_eq!(m2.data(&store)[0], 0);
        m1.data_mut(&mut store)[0] = 42;
        assert_eq!(m1.data(&mut store)[0], 42);
        assert_eq!(m2.data(&mut store)[0], 42);

        // And therefore their hash keys are the same.
        assert!(m1.hash_key(&store.as_context().0) == m2.hash_key(&store.as_context().0));

        // But the hash keys are different from different memories.
        let instance2 = Instance::new(&mut store, &module, &[])?;
        let m3 = instance2.get_memory(&mut store, "m").unwrap();
        assert!(m1.hash_key(&store.as_context().0) != m3.hash_key(&store.as_context().0));

        Ok(())
    }

    /// Offset of the data segment used by the `MemoryImage` tests: inside the
    /// second Wasm page, but not at the start of a host page.
    #[cfg(all(target_os = "linux", not(miri)))]
    const IMAGE_DATA_OFFSET: usize = 0x10000 + 8;

    /// Compiles a module whose single memory is initialized by one data segment
    /// at `IMAGE_DATA_OFFSET` and returns the CoW image Wasmtime builds for it.
    /// The module is never instantiated, we just take the image of the memory.
    #[cfg(all(target_os = "linux", not(miri)))]
    fn memory_image_for_data(data: &str) -> Result<MemoryImage> {
        let mut config = Config::new();
        config.memory_init_cow(true);
        let engine = Engine::new(&config)?;
        let module = Module::new(
            &engine,
            // Module with (at least) 2 pages of memory with data written at IMAGE_DATA_OFFSET.
            format!("(module (memory 2) (data (i32.const {IMAGE_DATA_OFFSET}) \"{data}\"))"),
        )?;
        let images = module.memory_images()?.expect("module has memory images");
        let image = images
            .get_memory_image(wasmtime_environ::DefinedMemoryIndex::from_u32(0))
            .expect("memory 0 has an image");
        Ok(MemoryImage::new(image.clone()))
    }

    /// The public accessors report the internal image's placement, and:
    /// - both values are multiples of the host page size; and
    /// - the image covers the module's data.
    #[test]
    #[cfg(all(target_os = "linux", not(miri)))]
    fn memory_image_accessors() -> Result<()> {
        let page_size = crate::runtime::vm::host_page_size();
        let image = memory_image_for_data("hello")?;
        let offset = image.linear_memory_offset();
        let len = image.len();

        assert_eq!(offset, image.vm().linear_memory_offset());
        assert_eq!(len, image.vm().len());
        assert_eq!(offset % page_size, 0);
        assert_eq!(len % page_size, 0);
        assert!(!image.is_empty());
        // Image starts at or before the data...
        assert!(offset <= IMAGE_DATA_OFFSET);
        // ... and reaches past the end of the data.
        assert!(offset + len >= IMAGE_DATA_OFFSET + "hello".len());

        let data = image.data();
        assert_eq!(data.len(), len);
        assert_eq!(data, image.vm().data());
        let data_start = IMAGE_DATA_OFFSET - offset;
        assert_eq!(&data[data_start..][..5], b"hello");
        assert!(data[..data_start].iter().all(|b| *b == 0));
        assert!(data[data_start + 5..].iter().all(|b| *b == 0));

        // Clones share the same underlying image.
        let clone = image.clone();
        assert!(core::ptr::eq(clone.vm(), image.vm()));
        Ok(())
    }

    #[test]
    #[cfg(all(target_os = "linux", not(miri)))]
    fn memory_image_identity() -> Result<()> {
        use std::hash::{BuildHasher, RandomState};

        let mut config = Config::new();
        config.memory_init_cow(true);
        let engine = Engine::new(&config)?;
        let wat = r#"(module (memory 1) (data (i32.const 0) "hello"))"#;
        let image_of = |module: &Module| -> Result<MemoryImage> {
            let images = module.memory_images()?.expect("module has memory images");
            let image = images
                .get_memory_image(wasmtime_environ::DefinedMemoryIndex::from_u32(0))
                .expect("memory 0 has an image");
            Ok(MemoryImage::new(image.clone()))
        };

        let module = Module::new(&engine, wat)?;
        let image = image_of(&module)?;
        let same = image_of(&module)?; // Same module instance gives the same image.
        let clone = image.clone(); // Clone just clones an Arc.

        assert_eq!(image, same);
        assert_eq!(image, clone);

        let hasher = RandomState::new();
        assert_eq!(hasher.hash_one(&image), hasher.hash_one(&same));
        assert_eq!(hasher.hash_one(&image), hasher.hash_one(&clone));

        Ok(())
    }

    /// `MemoryImage::map_at` places the image's bytes at
    /// `base + linear_memory_offset()` and zeroes the rest.
    #[test]
    #[cfg(all(target_os = "linux", not(miri)))]
    fn memory_image_map_at() -> Result<()> {
        use crate::runtime::vm::{HostAlignedByteCount, Mmap};

        let image = memory_image_for_data("hello")?;
        let size =
            HostAlignedByteCount::new_rounded_up(image.linear_memory_offset() + image.len())?;
        let mmap = Mmap::accessible_reserved(HostAlignedByteCount::ZERO, size)?;
        let base = mmap.as_non_null().as_ptr();

        // SAFETY: `mmap` was just created, is owned by this test and covers
        // the whole range the image is mapped into.
        unsafe { image.map_at(base)? };

        // SAFETY: `map_at` made the image's range readable.
        let mapped = unsafe {
            core::slice::from_raw_parts(base.add(image.linear_memory_offset()), image.len())
        };
        let data_start = IMAGE_DATA_OFFSET - image.linear_memory_offset();

        assert_eq!(mapped, image.data());
        assert_eq!(&mapped[data_start..][..5], b"hello");
        assert!(mapped[..data_start].iter().all(|b| *b == 0));
        assert!(mapped[data_start + 5..].iter().all(|b| *b == 0));

        Ok(())
    }
}