memmapix 0.9.0

#![deny(clippy::all, clippy::pedantic)]
#![allow(
    // pedantic exceptions
    clippy::cast_possible_truncation,
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::doc_markdown,
    clippy::explicit_deref_methods,
    clippy::missing_errors_doc,
    clippy::module_name_repetitions,
    clippy::must_use_candidate,
    clippy::needless_pass_by_value,
    clippy::return_self_not_must_use,
    clippy::unreadable_literal,
    clippy::upper_case_acronyms,
)]

//! A cross-platform Rust API for memory mapped buffers.
//!
//! The core functionality is provided by either [`Mmap`] or [`MmapMut`],
//! which correspond to mapping a [`File`] to a [`&[u8]`](https://doc.rust-lang.org/std/primitive.slice.html)
//! or [`&mut [u8]`](https://doc.rust-lang.org/std/primitive.slice.html)
//! respectively. Both function by dereferencing to a slice, allowing the
//! [`Mmap`]/[`MmapMut`] to be used in the same way you would the equivalent slice
//! types.
//!
//! [`File`]: std::fs::File
//!
//! # Examples
//!
//! For simple cases [`Mmap`] can be used directly:
//!
//! ```
//! use std::fs::File;
//! use std::io::Read;
//!
//! use memmapix::Mmap;
//!
//! # fn main() -> std::io::Result<()> {
//! let mut file = File::open("LICENSE-APACHE")?;
//!
//! let mut contents = Vec::new();
//! file.read_to_end(&mut contents)?;
//!
//! let mmap = unsafe { Mmap::map(&file)?  };
//!
//! assert_eq!(&contents[..], &mmap[..]);
//! # Ok(())
//! # }
//! ```
//!
//! However for cases which require configuration of the mapping, then
//! you can use [`MmapOptions`] in order to further configure a mapping
//! before you create it.

#![allow(clippy::len_without_is_empty, clippy::missing_safety_doc)]

#[cfg_attr(unix, path = "unix.rs")]
#[cfg_attr(windows, path = "windows.rs")]
#[cfg_attr(not(any(unix, windows)), path = "stub.rs")]
mod os;
use crate::os::{file_len, MmapInner};

#[cfg(unix)]
mod advice;
#[cfg(unix)]
pub use crate::advice::{Advice, UncheckedAdvice};

#[cfg(not(any(unix, windows)))]
use std::fs::File;
#[cfg(unix)]
use std::os::unix::io::{AsFd, BorrowedFd};
#[cfg(windows)]
use std::os::windows::io::{AsHandle, BorrowedHandle};
use std::{
  fmt,
  io::{Error, ErrorKind, Result},
  ops::{Deref, DerefMut},
  slice,
};

#[cfg(not(any(unix, windows)))]
pub struct MmapRawDescriptor<'a>(&'a File);

#[cfg(unix)]
pub struct MmapRawDescriptor<'a>(BorrowedFd<'a>);

#[cfg(windows)]
pub struct MmapRawDescriptor<'a>(BorrowedHandle<'a>);

/// Types that can provide a borrowed file descriptor/handle to a memory map
/// constructor.
///
/// The trait is implemented by anything that implements the I/O-safety
/// traits [`AsFd`] (Unix) or [`AsHandle`] (Windows), which guarantees at the
/// type-system level that the descriptor is open for the lifetime of the
/// returned borrow. Bare `RawFd`/`RawHandle` integers intentionally do
/// **not** implement this trait: safely obtaining a `BorrowedFd` /
/// `BorrowedHandle` from a raw integer requires [`BorrowedFd::borrow_raw`] /
/// [`BorrowedHandle::borrow_raw`], which are `unsafe fn`s whose validity
/// precondition must be upheld by the caller. Users holding a bare raw
/// descriptor should construct the borrow themselves in an `unsafe` block
/// before calling into this crate.
pub trait MmapAsRawDesc {
  fn as_raw_desc(&self) -> MmapRawDescriptor<'_>;
}

#[cfg(not(any(unix, windows)))]
impl MmapAsRawDesc for &File {
  fn as_raw_desc(&self) -> MmapRawDescriptor<'_> {
    MmapRawDescriptor(self)
  }
}

#[cfg(unix)]
impl<T: AsFd + ?Sized> MmapAsRawDesc for T {
  fn as_raw_desc(&self) -> MmapRawDescriptor<'_> {
    MmapRawDescriptor(self.as_fd())
  }
}

#[cfg(windows)]
impl<T: AsHandle + ?Sized> MmapAsRawDesc for T {
  fn as_raw_desc(&self) -> MmapRawDescriptor<'_> {
    MmapRawDescriptor(self.as_handle())
  }
}

/// Validates a range-scoped API's `offset`/`len` and reports whether the
/// caller should invoke its OS backend.
///
/// Returns `Ok(true)` when the backend should be called, `Ok(false)` when
/// the range is a valid no-op (`len == 0`), and `Err(InvalidInput)` when
/// `offset + len` overflows or exceeds `map_len`.
///
/// The zero-length short-circuit prevents two hazards:
///
/// 1. When `offset == map_len && len == 0`, dispatching to the backend would
///    materialize a one-past-the-end pointer via `ptr.offset(map_len)` /
///    `ptr.add(map_len)`. Computing such a pointer is permitted by Rust,
///    but handing it to the OS backend is at best noise and at worst
///    ill-defined per the platform's API contract.
/// 2. On Windows `FlushViewOfFile(ptr, 0)` is documented to flush "from
///    the base address to the end of the mapping" — it is *not* a no-op.
///    Calling safe `flush_range(o, 0)` must not silently become a
///    full-range flush.
fn check_range(offset: usize, len: usize, map_len: usize) -> Result<bool> {
  let end = offset
    .checked_add(len)
    .ok_or_else(|| Error::new(ErrorKind::InvalidInput, "offset + len overflows usize"))?;
  if end > map_len {
    return Err(Error::new(
      ErrorKind::InvalidInput,
      "offset + len exceeds the memory map's length",
    ));
  }
  Ok(len != 0)
}

/// A memory map builder, providing advanced options and flags for specifying memory map behavior.
///
/// `MmapOptions` can be used to create an anonymous memory map using [`map_anon()`], or a
/// file-backed memory map using one of [`map()`], [`map_mut()`], [`map_exec()`],
/// [`map_copy()`], or [`map_copy_read_only()`].
///
/// ## Safety
///
/// All file-backed memory map constructors are marked `unsafe` because of the potential for
/// *Undefined Behavior* (UB) using the map if the underlying file is subsequently modified, in or
/// out of process. Applications must consider the risk and take appropriate precautions when
/// using file-backed maps. Solutions such as file permissions, locks or process-private (e.g.
/// unlinked) files exist but are platform specific and limited.
///
/// [`map_anon()`]: MmapOptions::map_anon()
/// [`map()`]: MmapOptions::map()
/// [`map_mut()`]: MmapOptions::map_mut()
/// [`map_exec()`]: MmapOptions::map_exec()
/// [`map_copy()`]: MmapOptions::map_copy()
/// [`map_copy_read_only()`]: MmapOptions::map_copy_read_only()
#[derive(Clone, Debug, Default)]
pub struct MmapOptions {
  offset: u64,
  len: Option<usize>,
  huge: Option<u8>,
  stack: bool,
  populate: bool,
  no_reserve_swap: bool,
}

impl MmapOptions {
  /// Creates a new set of options for configuring and creating a memory map.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::{MmapMut, MmapOptions};
  /// # use std::io::Result;
  ///
  /// # fn main() -> Result<()> {
  /// // Create a new memory map builder.
  /// let mut mmap_options = MmapOptions::new();
  ///
  /// // Configure the memory map builder using option setters, then create
  /// // a memory map using one of `mmap_options.map_anon`, `mmap_options.map`,
  /// // `mmap_options.map_mut`, `mmap_options.map_exec`, or `mmap_options.map_copy`:
  /// let mut mmap: MmapMut = mmap_options.len(36).map_anon()?;
  ///
  /// // Use the memory map:
  /// mmap.copy_from_slice(b"...data to copy to the memory map...");
  /// # Ok(())
  /// # }
  /// ```
  pub fn new() -> MmapOptions {
    MmapOptions::default()
  }

  /// Configures the memory map to start at byte `offset` from the beginning of the file.
  ///
  /// This option has no effect on anonymous memory maps.
  ///
  /// By default, the offset is 0.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mmap = unsafe {
  ///     MmapOptions::new()
  ///                 .offset(30)
  ///                 .map(&File::open("LICENSE-APACHE")?)?
  /// };
  /// assert_eq!(&b"Apache License"[..],
  ///            &mmap[..14]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn offset(&mut self, offset: u64) -> &mut Self {
    self.offset = offset;
    self
  }

  /// Configures the created memory mapped buffer to be `len` bytes long.
  ///
  /// This option is mandatory for anonymous memory maps.
  ///
  /// For file-backed memory maps, the length will default to the file length.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mmap = unsafe {
  ///     MmapOptions::new()
  ///                 .len(6)
  ///                 .offset(30)
  ///                 .map(&File::open("LICENSE-APACHE")?)?
  /// };
  /// assert_eq!(&b"Apache"[..], &mmap[..]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn len(&mut self, len: usize) -> &mut Self {
    self.len = Some(len);
    self
  }

  fn validate_len(len: u64) -> Result<usize> {
    // Rust's slice cannot be larger than isize::MAX.
    // See https://doc.rust-lang.org/std/slice/fn.from_raw_parts.html
    //
    // This is not a problem on 64-bit targets, but on 32-bit one
    // having a file or an anonymous mapping larger than 2GB is quite normal
    // and we have to prevent it.
    if isize::try_from(len).is_err() {
      return Err(Error::new(
        ErrorKind::InvalidData,
        "memory map length overflows isize",
      ));
    }
    // If an unsigned number (u64) fits in isize, then it fits in usize.
    Ok(len as usize)
  }

  /// Returns the configured length, or the length of the provided file.
  fn get_len<T: MmapAsRawDesc>(&self, file: &T) -> Result<usize> {
    let len = if let Some(len) = self.len {
      len as u64
    } else {
      let desc = file.as_raw_desc();
      let file_len = file_len(desc.0)?;

      if file_len < self.offset {
        return Err(Error::new(
          ErrorKind::InvalidData,
          "memory map offset is larger than length",
        ));
      }

      file_len - self.offset
    };
    Self::validate_len(len)
  }

  /// Configures the anonymous memory map to be suitable for a process or thread stack.
  ///
  /// This option corresponds to the `MAP_STACK` flag on Linux. It has no effect on Windows.
  ///
  /// This option has no effect on file-backed memory maps.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let stack = MmapOptions::new().stack().len(4096).map_anon();
  /// # Ok(())
  /// # }
  /// ```
  pub fn stack(&mut self) -> &mut Self {
    self.stack = true;
    self
  }

  /// Configures the anonymous memory map to be allocated using huge pages.
  ///
  /// This option corresponds to the `MAP_HUGETLB` flag on Linux. It has no effect on Windows.
  ///
  /// The size of the requested page can be specified in page bits. If not provided, the system
  /// default is requested. The requested length should be a multiple of this, or the mapping
  /// will fail.
  ///
  /// This option has no effect on file-backed memory maps.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let stack = MmapOptions::new().huge(Some(21)).len(2*1024*1024).map_anon();
  /// # Ok(())
  /// # }
  /// ```
  ///
  /// The number 21 corresponds to `MAP_HUGE_2MB`. See mmap(2) for more details.
  pub fn huge(&mut self, page_bits: Option<u8>) -> &mut Self {
    self.huge = Some(page_bits.unwrap_or(0));
    self
  }

  /// Populate (prefault) page tables for a mapping.
  ///
  /// For a file mapping, this causes read-ahead on the file. This will help to reduce blocking on page faults later.
  ///
  /// This option corresponds to the `MAP_POPULATE` flag on Linux. It has no effect on Windows.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let file = File::open("LICENSE-MIT")?;
  ///
  /// let mmap = unsafe {
  ///     MmapOptions::new().populate().map(&file)?
  /// };
  ///
  /// assert_eq!(&b"Copyright"[..], &mmap[..9]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn populate(&mut self) -> &mut Self {
    self.populate = true;
    self
  }

  /// Do not reserve swap space for the memory map.
  ///
  /// By default, platforms may reserve swap space for memory maps.
  /// This guarantees that a write to the mapped memory will succeed, even if physical memory is exhausted.
  /// Otherwise, the write to memory could fail (on Linux with a segfault).
  ///
  /// This option requests that no swap space will be allocated for the memory map,
  /// which can be useful for extremely large maps that are only written to sparsely.
  ///
  /// This option is currently supported on Linux, Android, Apple platforms (macOS, iOS, visionOS, etc.), NetBSD, Solaris and Illumos.
  /// On those platforms, this option corresponds to the `MAP_NORESERVE` flag.
  /// On Linux, this option is ignored if [`vm.overcommit_memory`](https://www.kernel.org/doc/Documentation/vm/overcommit-accounting) is set to 2.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let file = File::open("LICENSE-MIT")?;
  ///
  /// let mmap = unsafe {
  ///     MmapOptions::new().no_reserve_swap().map_copy(&file)?
  /// };
  ///
  /// assert_eq!(&b"Copyright"[..], &mmap[..9]);
  /// # Ok(())
  /// # }
  /// ```
  pub fn no_reserve_swap(&mut self) -> &mut Self {
    self.no_reserve_swap = true;
    self
  }

  /// Creates a read-only memory map backed by a file.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapOptions] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  /// use std::io::Read;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mut file = File::open("LICENSE-APACHE")?;
  ///
  /// let mut contents = Vec::new();
  /// file.read_to_end(&mut contents)?;
  ///
  /// let mmap = unsafe {
  ///     MmapOptions::new().map(&file)?
  /// };
  ///
  /// assert_eq!(&contents[..], &mmap[..]);
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map<T: MmapAsRawDesc>(&self, file: T) -> Result<Mmap> {
    let desc = file.as_raw_desc();

    MmapInner::map(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| Mmap { inner })
  }

  /// Creates a readable and executable memory map backed by a file.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapOptions] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub unsafe fn map_exec<T: MmapAsRawDesc>(&self, file: T) -> Result<Mmap> {
    let desc = file.as_raw_desc();

    MmapInner::map_exec(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| Mmap { inner })
  }

  /// Creates a writeable memory map backed by a file.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapOptions] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read and write permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use std::fs::OpenOptions;
  /// use std::path::PathBuf;
  ///
  /// use memmapix::MmapOptions;
  /// #
  /// # fn main() -> std::io::Result<()> {
  /// # let tempdir = tempfile::tempdir()?;
  /// let path: PathBuf = /* path to file */
  /// #   tempdir.path().join("map_mut");
  /// let file = OpenOptions::new().read(true).write(true).create(true).truncate(true).open(&path)?;
  /// file.set_len(13)?;
  ///
  /// let mut mmap = unsafe {
  ///     MmapOptions::new().map_mut(&file)?
  /// };
  ///
  /// mmap.copy_from_slice(b"Hello, world!");
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map_mut<T: MmapAsRawDesc>(&self, file: T) -> Result<MmapMut> {
    let desc = file.as_raw_desc();

    MmapInner::map_mut(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| MmapMut { inner })
  }

  /// Creates a copy-on-write memory map backed by a file.
  ///
  /// Data written to the memory map will not be visible by other processes,
  /// and will not be carried through to the underlying file.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapOptions] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with writable permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  /// use std::io::Write;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let file = File::open("LICENSE-APACHE")?;
  /// let mut mmap = unsafe { MmapOptions::new().map_copy(&file)? };
  /// (&mut mmap[..]).write_all(b"Hello, world!")?;
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map_copy<T: MmapAsRawDesc>(&self, file: T) -> Result<MmapMut> {
    let desc = file.as_raw_desc();

    MmapInner::map_copy(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| MmapMut { inner })
  }

  /// Creates a copy-on-write read-only memory map backed by a file.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapOptions] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::MmapOptions;
  /// use std::fs::File;
  /// use std::io::Read;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mut file = File::open("README.md")?;
  ///
  /// let mut contents = Vec::new();
  /// file.read_to_end(&mut contents)?;
  ///
  /// let mmap = unsafe {
  ///     MmapOptions::new().map_copy_read_only(&file)?
  /// };
  ///
  /// assert_eq!(&contents[..], &mmap[..]);
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map_copy_read_only<T: MmapAsRawDesc>(&self, file: T) -> Result<Mmap> {
    let desc = file.as_raw_desc();

    MmapInner::map_copy_read_only(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| Mmap { inner })
  }

  /// Creates an anonymous memory map.
  ///
  /// The memory map length should be configured using [`MmapOptions::len()`]
  /// before creating an anonymous memory map, otherwise a zero-length mapping
  /// will be created.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails or
  /// when `len > isize::MAX`.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub fn map_anon(&self) -> Result<MmapMut> {
    let len = self.len.unwrap_or(0);

    // See get_len() for details.
    let len = Self::validate_len(len as u64)?;

    MmapInner::map_anon(
      len,
      self.stack,
      self.populate,
      self.huge,
      self.no_reserve_swap,
    )
    .map(|inner| MmapMut { inner })
  }

  /// Creates a raw memory map.
  ///
  /// Because [`MmapAsRawDesc`] is gated on [`AsFd`]/[`AsHandle`], the
  /// descriptor passed in carries a compiler-checked validity guarantee
  /// for the lifetime of the call — so this entry point is safe. Users
  /// holding a bare `RawFd`/`RawHandle` integer must first wrap it in a
  /// [`BorrowedFd::borrow_raw`]/[`BorrowedHandle::borrow_raw`] themselves
  /// (both `unsafe`) and pass that in.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read and write permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub fn map_raw<T: MmapAsRawDesc>(&self, file: T) -> Result<MmapRaw> {
    let desc = file.as_raw_desc();

    MmapInner::map_mut(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| MmapRaw { inner })
  }

  /// Creates a read-only raw memory map
  ///
  /// This is primarily useful to avoid intermediate `Mmap` instances when
  /// read-only access to files modified elsewhere are required.
  ///
  /// See [`MmapOptions::map_raw`] for the rationale of why this entry
  /// point is safe despite handing out raw pointers.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub fn map_raw_read_only<T: MmapAsRawDesc>(&self, file: T) -> Result<MmapRaw> {
    let desc = file.as_raw_desc();

    MmapInner::map(
      self.get_len(&file)?,
      desc.0,
      self.offset,
      self.populate,
      self.no_reserve_swap,
    )
    .map(|inner| MmapRaw { inner })
  }
}

/// A handle to an immutable memory mapped buffer.
///
/// A `Mmap` may be backed by a file, or it can be anonymous map, backed by volatile memory. Use
/// [`MmapOptions`] or [`map()`] to create a file-backed memory map. To create an immutable
/// anonymous memory map, first create a mutable anonymous memory map, and then make it immutable
/// with [`MmapMut::make_read_only()`].
///
/// A file backed `Mmap` is created by `&File` reference, and will remain valid even after the
/// `File` is dropped. In other words, the `Mmap` handle is completely independent of the `File`
/// used to create it. For consistency, on some platforms this is achieved by duplicating the
/// underlying file handle. The memory will be unmapped when the `Mmap` handle is dropped.
///
/// Dereferencing and accessing the bytes of the buffer may result in page faults (e.g. swapping
/// the mapped pages into physical memory) though the details of this are platform specific.
///
/// `Mmap` is [`Sync`] and [`Send`].
///
/// See [`MmapMut`] for the mutable version.
///
/// ## Safety
///
/// All file-backed memory map constructors are marked `unsafe` because of the potential for
/// *Undefined Behavior* (UB) using the map if the underlying file is subsequently modified, in or
/// out of process. Applications must consider the risk and take appropriate precautions when using
/// file-backed maps. Solutions such as file permissions, locks or process-private (e.g. unlinked)
/// files exist but are platform specific and limited.
///
/// ## Example
///
/// ```
/// use memmapix::MmapOptions;
/// use std::io::Write;
/// use std::fs::File;
///
/// # fn main() -> std::io::Result<()> {
/// let file = File::open("LICENSE-APACHE")?;
/// let mmap = unsafe { MmapOptions::new().map(&file)? };
/// assert_eq!(b"Apache License", &mmap[30..44]);
/// # Ok(())
/// # }
/// ```
///
/// [`map()`]: Mmap::map()
pub struct Mmap {
  inner: MmapInner,
}

impl Mmap {
  /// Creates a read-only memory map backed by a file.
  ///
  /// This is equivalent to calling `MmapOptions::new().map(file)`.
  ///
  /// # Safety
  ///
  /// See the [type-level][Mmap] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use std::fs::File;
  /// use std::io::Read;
  ///
  /// use memmapix::Mmap;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mut file = File::open("LICENSE-APACHE")?;
  ///
  /// let mut contents = Vec::new();
  /// file.read_to_end(&mut contents)?;
  ///
  /// let mmap = unsafe { Mmap::map(&file)?  };
  ///
  /// assert_eq!(&contents[..], &mmap[..]);
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map<T: MmapAsRawDesc>(file: T) -> Result<Mmap> {
    MmapOptions::new().map(file)
  }

  /// Transition the memory map to be writable.
  ///
  /// If the memory map is file-backed, the file must have been opened with write permissions.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with writable permissions.
  ///
  /// # Example
  ///
  /// ```
  /// use memmapix::Mmap;
  /// use std::ops::DerefMut;
  /// use std::io::Write;
  /// # use std::fs::OpenOptions;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// # let tempdir = tempfile::tempdir()?;
  /// let file = /* file opened with write permissions */
  /// #          OpenOptions::new()
  /// #                      .read(true)
  /// #                      .write(true)
  /// #                      .create(true)
  /// #                      .truncate(true)
  /// #                      .open(tempdir.path()
  /// #                      .join("make_mut"))?;
  /// # file.set_len(128)?;
  /// let mmap = unsafe { Mmap::map(&file)? };
  /// // ... use the read-only memory map ...
  /// let mut mut_mmap = mmap.make_mut()?;
  /// mut_mmap.deref_mut().write_all(b"hello, world!")?;
  /// # Ok(())
  /// # }
  /// ```
  pub fn make_mut(mut self) -> Result<MmapMut> {
    self.inner.make_mut()?;
    Ok(MmapMut { inner: self.inner })
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise(&self, advice: Advice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// Only supported on Unix.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise_range(&self, advice: Advice, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise_range(
    &self,
    advice: UncheckedAdvice,
    offset: usize,
    len: usize,
  ) -> Result<()> {
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Lock the whole memory map into RAM. Only supported on Unix.
  ///
  /// See [mlock()](https://man7.org/linux/man-pages/man2/mlock.2.html) map page.
  #[cfg(unix)]
  pub fn lock(&self) -> Result<()> {
    self.inner.lock()
  }

  /// Unlock the whole memory map. Only supported on Unix.
  ///
  /// See [munlock()](https://man7.org/linux/man-pages/man2/munlock.2.html) map page.
  #[cfg(unix)]
  pub fn unlock(&self) -> Result<()> {
    self.inner.unlock()
  }

  /// Adjust the size of the memory mapping.
  ///
  /// This will try to resize the memory mapping in place. If
  /// [`RemapOptions::may_move`] is specified it will move the mapping if it
  /// could not resize in place, otherwise it will error.
  ///
  /// Only supported on Linux.
  ///
  /// See the [`mremap(2)`] man page.
  ///
  /// # Safety
  ///
  /// Resizing the memory mapping beyond the end of the mapped file will
  /// result in UB should you happen to access memory beyond the end of the
  /// file.
  ///
  /// [`mremap(2)`]: https://man7.org/linux/man-pages/man2/mremap.2.html
  #[cfg(target_os = "linux")]
  pub unsafe fn remap(&mut self, new_len: usize, options: RemapOptions) -> Result<()> {
    self.inner.remap(new_len, options)
  }
}

#[cfg(feature = "stable_deref_trait")]
unsafe impl stable_deref_trait::StableDeref for Mmap {}

impl Deref for Mmap {
  type Target = [u8];

  #[inline]
  fn deref(&self) -> &[u8] {
    unsafe { slice::from_raw_parts(self.inner.ptr(), self.inner.len()) }
  }
}

impl AsRef<[u8]> for Mmap {
  #[inline]
  fn as_ref(&self) -> &[u8] {
    self.deref()
  }
}

impl fmt::Debug for Mmap {
  fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
    fmt
      .debug_struct("Mmap")
      .field("ptr", &self.as_ptr())
      .field("len", &self.len())
      .finish()
  }
}

/// A handle to a raw memory mapped buffer.
///
/// This struct never hands out references to its interior, only raw pointers.
/// This can be helpful when creating shared memory maps between untrusted processes.
///
/// For the safety concerns that arise when converting these raw pointers to references,
/// see the [`Mmap`] safety documentation.
pub struct MmapRaw {
  inner: MmapInner,
}

impl MmapRaw {
  /// Creates a writeable memory map backed by a file.
  ///
  /// This is equivalent to calling `MmapOptions::new().map_raw(file)`.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read and write permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub fn map_raw<T: MmapAsRawDesc>(file: T) -> Result<MmapRaw> {
    MmapOptions::new().map_raw(file)
  }

  /// Returns a raw pointer to the memory mapped file.
  ///
  /// Before dereferencing this pointer, you have to make sure that the file has not been
  /// truncated since the memory map was created.
  /// Avoiding this will not introduce memory safety issues in Rust terms,
  /// but will cause SIGBUS (or equivalent) signal.
  #[inline]
  pub fn as_ptr(&self) -> *const u8 {
    self.inner.ptr()
  }

  /// Returns an unsafe mutable pointer to the memory mapped file.
  ///
  /// Before dereferencing this pointer, you have to make sure that the file has not been
  /// truncated since the memory map was created.
  /// Avoiding this will not introduce memory safety issues in Rust terms,
  /// but will cause SIGBUS (or equivalent) signal.
  #[inline]
  pub fn as_mut_ptr(&self) -> *mut u8 {
    self.inner.ptr() as *mut u8
  }

  /// Returns the length in bytes of the memory map.
  ///
  /// Note that truncating the file can cause the length to change (and render this value unusable).
  #[inline]
  pub fn len(&self) -> usize {
    self.inner.len()
  }

  /// Flushes outstanding memory map modifications to disk.
  ///
  /// When this method returns with a non-error result, all outstanding changes to a file-backed
  /// memory map are guaranteed to be durably stored. The file's metadata (including last
  /// modification timestamp) may not be updated.
  ///
  /// # Example
  ///
  /// ```
  /// use std::fs::OpenOptions;
  /// use std::io::Write;
  /// use std::path::PathBuf;
  /// use std::slice;
  ///
  /// use memmapix::MmapRaw;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let tempdir = tempfile::tempdir()?;
  /// let path: PathBuf = /* path to file */
  /// #   tempdir.path().join("flush");
  /// let file = OpenOptions::new().read(true).write(true).create(true).truncate(true).open(&path)?;
  /// file.set_len(128)?;
  ///
  /// let mut mmap = unsafe { MmapRaw::map_raw(&file)? };
  ///
  /// let mut memory = unsafe { slice::from_raw_parts_mut(mmap.as_mut_ptr(), 128) };
  /// memory.write_all(b"Hello, world!")?;
  /// mmap.flush()?;
  /// # Ok(())
  /// # }
  /// ```
  pub fn flush(&self) -> Result<()> {
    let len = self.len();
    self.inner.flush(0, len)
  }

  /// Asynchronously flushes outstanding memory map modifications to disk.
  ///
  /// This method initiates flushing modified pages to durable storage, but it will not wait for
  /// the operation to complete before returning. The file's metadata (including last
  /// modification timestamp) may not be updated.
  pub fn flush_async(&self) -> Result<()> {
    let len = self.len();
    self.inner.flush_async(0, len)
  }

  /// Flushes outstanding memory map modifications in the range to disk.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// When this method returns with a non-error result, all outstanding changes to a file-backed
  /// memory in the range are guaranteed to be durable stored. The file's metadata (including
  /// last modification timestamp) may not be updated. It is not guaranteed the only the changes
  /// in the specified range are flushed; other outstanding changes to the memory map may be
  /// flushed as well.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  pub fn flush_range(&self, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.flush(offset, len)
  }

  /// Asynchronously flushes outstanding memory map modifications in the range to disk.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// This method initiates flushing modified pages to durable storage, but it will not wait for
  /// the operation to complete before returning. The file's metadata (including last
  /// modification timestamp) may not be updated. It is not guaranteed that the only changes
  /// flushed are those in the specified range; other outstanding changes to the memory map may
  /// be flushed as well.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  pub fn flush_async_range(&self, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.flush_async(offset, len)
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise(&self, advice: Advice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// Only supported on Unix.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise_range(&self, advice: Advice, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise_range(
    &self,
    advice: UncheckedAdvice,
    offset: usize,
    len: usize,
  ) -> Result<()> {
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Lock the whole memory map into RAM. Only supported on Unix.
  ///
  /// See [mlock()](https://man7.org/linux/man-pages/man2/mlock.2.html) map page.
  #[cfg(unix)]
  pub fn lock(&self) -> Result<()> {
    self.inner.lock()
  }

  /// Unlock the whole memory map. Only supported on Unix.
  ///
  /// See [munlock()](https://man7.org/linux/man-pages/man2/munlock.2.html) map page.
  #[cfg(unix)]
  pub fn unlock(&self) -> Result<()> {
    self.inner.unlock()
  }

  /// Adjust the size of the memory mapping.
  ///
  /// This will try to resize the memory mapping in place. If
  /// [`RemapOptions::may_move`] is specified it will move the mapping if it
  /// could not resize in place, otherwise it will error.
  ///
  /// Only supported on Linux.
  ///
  /// See the [`mremap(2)`] man page.
  ///
  /// # Safety
  ///
  /// Resizing the memory mapping beyond the end of the mapped file will
  /// result in UB should you happen to access memory beyond the end of the
  /// file.
  ///
  /// [`mremap(2)`]: https://man7.org/linux/man-pages/man2/mremap.2.html
  #[cfg(target_os = "linux")]
  pub unsafe fn remap(&mut self, new_len: usize, options: RemapOptions) -> Result<()> {
    self.inner.remap(new_len, options)
  }
}

impl fmt::Debug for MmapRaw {
  fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
    fmt
      .debug_struct("MmapRaw")
      .field("ptr", &self.as_ptr())
      .field("len", &self.len())
      .finish()
  }
}

impl From<Mmap> for MmapRaw {
  fn from(value: Mmap) -> Self {
    Self { inner: value.inner }
  }
}

impl From<MmapMut> for MmapRaw {
  fn from(value: MmapMut) -> Self {
    Self { inner: value.inner }
  }
}

/// A handle to a mutable memory mapped buffer.
///
/// A file-backed `MmapMut` buffer may be used to read from or write to a file. An anonymous
/// `MmapMut` buffer may be used any place that an in-memory byte buffer is needed. Use
/// [`MmapMut::map_mut()`] and [`MmapMut::map_anon()`] to create a mutable memory map of the
/// respective types, or [`MmapOptions::map_mut()`] and [`MmapOptions::map_anon()`] if non-default
/// options are required.
///
/// A file backed `MmapMut` is created by `&File` reference, and will remain valid even after the
/// `File` is dropped. In other words, the `MmapMut` handle is completely independent of the `File`
/// used to create it. For consistency, on some platforms this is achieved by duplicating the
/// underlying file handle. The memory will be unmapped when the `MmapMut` handle is dropped.
///
/// Dereferencing and accessing the bytes of the buffer may result in page faults (e.g. swapping
/// the mapped pages into physical memory) though the details of this are platform specific.
///
/// `MmapMut` is [`Sync`] and [`Send`].
///
/// See [`Mmap`] for the immutable version.
///
/// ## Safety
///
/// All file-backed memory map constructors are marked `unsafe` because of the potential for
/// *Undefined Behavior* (UB) using the map if the underlying file is subsequently modified, in or
/// out of process. Applications must consider the risk and take appropriate precautions when using
/// file-backed maps. Solutions such as file permissions, locks or process-private (e.g. unlinked)
/// files exist but are platform specific and limited.
pub struct MmapMut {
  inner: MmapInner,
}

impl MmapMut {
  /// Creates a writeable memory map backed by a file.
  ///
  /// This is equivalent to calling `MmapOptions::new().map_mut(file)`.
  ///
  /// # Safety
  ///
  /// See the [type-level][MmapMut] docs for why this function is unsafe.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file is not open with read and write permissions.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  ///
  /// # Example
  ///
  /// ```
  /// use std::fs::OpenOptions;
  /// use std::path::PathBuf;
  ///
  /// use memmapix::MmapMut;
  /// #
  /// # fn main() -> std::io::Result<()> {
  /// # let tempdir = tempfile::tempdir()?;
  /// let path: PathBuf = /* path to file */
  /// #   tempdir.path().join("map_mut");
  /// let file = OpenOptions::new()
  ///                        .read(true)
  ///                        .write(true)
  ///                        .create(true)
  ///                        .truncate(true)
  ///                        .open(&path)?;
  /// file.set_len(13)?;
  ///
  /// let mut mmap = unsafe { MmapMut::map_mut(&file)? };
  ///
  /// mmap.copy_from_slice(b"Hello, world!");
  /// # Ok(())
  /// # }
  /// ```
  pub unsafe fn map_mut<T: MmapAsRawDesc>(file: T) -> Result<MmapMut> {
    MmapOptions::new().map_mut(file)
  }

  /// Creates an anonymous memory map.
  ///
  /// This is equivalent to calling `MmapOptions::new().len(length).map_anon()`.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails or
  /// when `len > isize::MAX`.
  ///
  /// Returns [`ErrorKind::Unsupported`] on unsupported platforms.
  pub fn map_anon(length: usize) -> Result<MmapMut> {
    MmapOptions::new().len(length).map_anon()
  }

  /// Flushes outstanding memory map modifications to disk.
  ///
  /// When this method returns with a non-error result, all outstanding changes to a file-backed
  /// memory map are guaranteed to be durably stored. The file's metadata (including last
  /// modification timestamp) may not be updated.
  ///
  /// # Example
  ///
  /// ```
  /// use std::fs::OpenOptions;
  /// use std::io::Write;
  /// use std::path::PathBuf;
  ///
  /// use memmapix::MmapMut;
  ///
  /// # fn main() -> std::io::Result<()> {
  /// # let tempdir = tempfile::tempdir()?;
  /// let path: PathBuf = /* path to file */
  /// #   tempdir.path().join("flush");
  /// let file = OpenOptions::new().read(true).write(true).create(true).truncate(true).open(&path)?;
  /// file.set_len(128)?;
  ///
  /// let mut mmap = unsafe { MmapMut::map_mut(&file)? };
  ///
  /// (&mut mmap[..]).write_all(b"Hello, world!")?;
  /// mmap.flush()?;
  /// # Ok(())
  /// # }
  /// ```
  pub fn flush(&self) -> Result<()> {
    let len = self.len();
    self.inner.flush(0, len)
  }

  /// Asynchronously flushes outstanding memory map modifications to disk.
  ///
  /// This method initiates flushing modified pages to durable storage, but it will not wait for
  /// the operation to complete before returning. The file's metadata (including last
  /// modification timestamp) may not be updated.
  pub fn flush_async(&self) -> Result<()> {
    let len = self.len();
    self.inner.flush_async(0, len)
  }

  /// Flushes outstanding memory map modifications in the range to disk.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// When this method returns with a non-error result, all outstanding changes to a file-backed
  /// memory in the range are guaranteed to be durable stored. The file's metadata (including
  /// last modification timestamp) may not be updated. It is not guaranteed the only the changes
  /// in the specified range are flushed; other outstanding changes to the memory map may be
  /// flushed as well.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  pub fn flush_range(&self, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.flush(offset, len)
  }

  /// Asynchronously flushes outstanding memory map modifications in the range to disk.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// This method initiates flushing modified pages to durable storage, but it will not wait for
  /// the operation to complete before returning. The file's metadata (including last
  /// modification timestamp) may not be updated. It is not guaranteed that the only changes
  /// flushed are those in the specified range; other outstanding changes to the memory map may
  /// be flushed as well.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  pub fn flush_async_range(&self, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.flush_async(offset, len)
  }

  /// Returns an immutable version of this memory mapped buffer.
  ///
  /// If the memory map is file-backed, the file must have been opened with read permissions.
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file has not been opened with read permissions.
  ///
  /// # Example
  ///
  /// ```
  /// use std::io::Write;
  /// use std::path::PathBuf;
  ///
  /// use memmapix::{Mmap, MmapMut};
  ///
  /// # fn main() -> std::io::Result<()> {
  /// let mut mmap = MmapMut::map_anon(128)?;
  ///
  /// (&mut mmap[..]).write(b"Hello, world!")?;
  ///
  /// let mmap: Mmap = mmap.make_read_only()?;
  /// # Ok(())
  /// # }
  /// ```
  pub fn make_read_only(mut self) -> Result<Mmap> {
    self.inner.make_read_only()?;
    Ok(Mmap { inner: self.inner })
  }

  /// Transition the memory map to be readable and executable.
  ///
  /// If the memory map is file-backed, the file must have been opened with execute permissions.
  ///
  /// On systems with separate instructions and data caches (a category that includes many ARM
  /// chips), a platform-specific call may be needed to ensure that the changes are visible to the
  /// execution unit (e.g. when using this function to implement a JIT compiler).  For more
  /// details, see [this ARM write-up](https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/caches-and-self-modifying-code)
  /// or the `man` page for [`sys_icache_invalidate`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/sys_icache_invalidate.3.html).
  ///
  /// # Errors
  ///
  /// This method returns an error when the underlying system call fails, which can happen for a
  /// variety of reasons, such as when the file has not been opened with execute permissions.
  pub fn make_exec(mut self) -> Result<Mmap> {
    self.inner.make_exec()?;
    Ok(Mmap { inner: self.inner })
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise(&self, advice: Advice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()> {
    self.inner.advise(advice.to_raw(), 0, self.inner.len())
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// Only supported on Unix.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// # Errors
  ///
  /// Returns [`ErrorKind::InvalidInput`] if `offset + len` overflows or
  /// exceeds the memory map's length.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub fn advise_range(&self, advice: Advice, offset: usize, len: usize) -> Result<()> {
    if !check_range(offset, len, self.inner.len())? {
      return Ok(());
    }
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Advise OS how this range of memory map will be accessed.
  ///
  /// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
  ///
  /// The offset and length must be in the bounds of the memory map.
  ///
  /// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
  #[cfg(unix)]
  pub unsafe fn unchecked_advise_range(
    &self,
    advice: UncheckedAdvice,
    offset: usize,
    len: usize,
  ) -> Result<()> {
    self.inner.advise(advice.to_raw(), offset, len)
  }

  /// Lock the whole memory map into RAM. Only supported on Unix.
  ///
  /// See [mlock()](https://man7.org/linux/man-pages/man2/mlock.2.html) map page.
  #[cfg(unix)]
  pub fn lock(&self) -> Result<()> {
    self.inner.lock()
  }

  /// Unlock the whole memory map. Only supported on Unix.
  ///
  /// See [munlock()](https://man7.org/linux/man-pages/man2/munlock.2.html) map page.
  #[cfg(unix)]
  pub fn unlock(&self) -> Result<()> {
    self.inner.unlock()
  }

  /// Adjust the size of the memory mapping.
  ///
  /// This will try to resize the memory mapping in place. If
  /// [`RemapOptions::may_move`] is specified it will move the mapping if it
  /// could not resize in place, otherwise it will error.
  ///
  /// Only supported on Linux.
  ///
  /// See the [`mremap(2)`] man page.
  ///
  /// # Safety
  ///
  /// Resizing the memory mapping beyond the end of the mapped file will
  /// result in UB should you happen to access memory beyond the end of the
  /// file.
  ///
  /// [`mremap(2)`]: https://man7.org/linux/man-pages/man2/mremap.2.html
  #[cfg(target_os = "linux")]
  pub unsafe fn remap(&mut self, new_len: usize, options: RemapOptions) -> Result<()> {
    self.inner.remap(new_len, options)
  }
}

#[cfg(feature = "stable_deref_trait")]
unsafe impl stable_deref_trait::StableDeref for MmapMut {}

impl Deref for MmapMut {
  type Target = [u8];

  #[inline]
  fn deref(&self) -> &[u8] {
    unsafe { slice::from_raw_parts(self.inner.ptr(), self.inner.len()) }
  }
}

impl DerefMut for MmapMut {
  #[inline]
  fn deref_mut(&mut self) -> &mut [u8] {
    unsafe { slice::from_raw_parts_mut(self.inner.mut_ptr(), self.inner.len()) }
  }
}

impl AsRef<[u8]> for MmapMut {
  #[inline]
  fn as_ref(&self) -> &[u8] {
    self.deref()
  }
}

impl AsMut<[u8]> for MmapMut {
  #[inline]
  fn as_mut(&mut self) -> &mut [u8] {
    self.deref_mut()
  }
}

impl fmt::Debug for MmapMut {
  fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
    fmt
      .debug_struct("MmapMut")
      .field("ptr", &self.as_ptr())
      .field("len", &self.len())
      .finish()
  }
}

/// Options for [`Mmap::remap`] and [`MmapMut::remap`].
#[derive(Copy, Clone, Default, Debug)]
#[cfg(target_os = "linux")]
pub struct RemapOptions {
  may_move: bool,
}

#[cfg(target_os = "linux")]
impl RemapOptions {
  /// Creates a mew set of options for resizing a memory map.
  pub fn new() -> Self {
    Self::default()
  }

  /// Controls whether the memory map can be moved if it is not possible to
  /// resize it in place.
  ///
  /// If false then the memory map is guaranteed to remain at the same
  /// address when being resized but attempting to resize will return an
  /// error if the new memory map would overlap with something else in the
  /// current process' memory.
  ///
  /// By default this is false.
  ///
  /// # `may_move` and `StableDeref`
  /// If the `stable_deref_trait` feature is enabled then [`Mmap`] and
  /// [`MmapMut`] implement `StableDeref`. `StableDeref` promises that the
  /// memory map dereferences to a fixed address, however, calling `remap`
  /// with `may_move` set may result in the backing memory of the mapping
  /// being moved to a new address. This may cause UB in other code
  /// depending on the `StableDeref` guarantees.
  pub fn may_move(mut self, may_move: bool) -> Self {
    self.may_move = may_move;
    self
  }

  pub(crate) fn into_flags(self) -> rustix::mm::MremapFlags {
    if self.may_move {
      rustix::mm::MremapFlags::MAYMOVE
    } else {
      rustix::mm::MremapFlags::empty()
    }
  }
}

#[cfg(test)]
mod test {
  #[cfg(unix)]
  use crate::advice::{Advice, UncheckedAdvice};
  #[cfg(unix)]
  use std::os::unix::io::{AsRawFd, BorrowedFd};
  #[cfg(windows)]
  use std::os::windows::fs::OpenOptionsExt;
  use std::{
    fs::{File, OpenOptions},
    io::{Read, Write},
    mem,
  };

  #[cfg(windows)]
  const GENERIC_ALL: u32 = 0x10000000;

  use super::{Mmap, MmapMut, MmapOptions, MmapRaw};

  #[test]
  fn map_file() {
    let expected_len = 128;
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();

    file.set_len(expected_len as u64).unwrap();

    let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    let len = mmap.len();
    assert_eq!(expected_len, len);

    let zeros = vec![0; len];
    let incr: Vec<u8> = (0..len as u8).collect();

    // check that the mmap is empty
    assert_eq!(&zeros[..], &mmap[..]);

    // write values into the mmap
    (&mut mmap[..]).write_all(&incr[..]).unwrap();

    // read values back
    assert_eq!(&incr[..], &mmap[..]);
  }

  #[test]
  #[cfg(unix)]
  fn map_fd() {
    let expected_len = 128;
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();

    file.set_len(expected_len as u64).unwrap();

    // Exercise the raw-fd path by wrapping a bare RawFd in a BorrowedFd.
    // Constructing the borrow is `unsafe` (caller asserts the fd is open);
    // the map call itself is safe only in contract: it remains `unsafe fn`
    // because of the file-modification UB caveat shared by all file-backed
    // `map_*` variants.
    let raw_fd = file.as_raw_fd();
    let mut mmap = unsafe { MmapMut::map_mut(BorrowedFd::borrow_raw(raw_fd)).unwrap() };
    let len = mmap.len();
    assert_eq!(expected_len, len);

    let zeros = vec![0; len];
    let incr: Vec<u8> = (0..len as u8).collect();

    // check that the mmap is empty
    assert_eq!(&zeros[..], &mmap[..]);

    // write values into the mmap
    (&mut mmap[..]).write_all(&incr[..]).unwrap();

    // read values back
    assert_eq!(&incr[..], &mmap[..]);
  }

  /// Checks that "mapping" a 0-length file derefs to an empty slice.
  #[test]
  fn map_empty_file() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    let mmap = unsafe { Mmap::map(&file).unwrap() };
    assert!(mmap.is_empty());
    assert_eq!(mmap.as_ptr().align_offset(mem::size_of::<usize>()), 0);
    let mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    assert!(mmap.is_empty());
    assert_eq!(mmap.as_ptr().align_offset(mem::size_of::<usize>()), 0);
  }

  #[test]
  fn map_anon() {
    let expected_len = 128;
    let mut mmap = MmapMut::map_anon(expected_len).unwrap();
    let len = mmap.len();
    assert_eq!(expected_len, len);

    let zeros = vec![0; len];
    let incr: Vec<u8> = (0..len as u8).collect();

    // check that the mmap is empty
    assert_eq!(&zeros[..], &mmap[..]);

    // write values into the mmap
    (&mut mmap[..]).write_all(&incr[..]).unwrap();

    // read values back
    assert_eq!(&incr[..], &mmap[..]);
  }

  #[test]
  fn map_anon_zero_len() {
    assert!(MmapOptions::new().map_anon().unwrap().is_empty());
  }

  #[test]
  #[cfg(target_pointer_width = "32")]
  fn map_anon_len_overflow() {
    let res = MmapMut::map_anon(0x80000000);

    assert_eq!(
      res.unwrap_err().to_string(),
      "memory map length overflows isize"
    );
  }

  #[test]
  fn file_write() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let mut file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(128).unwrap();

    let write = b"abc123";
    let mut read = [0u8; 6];

    let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    (&mut mmap[..]).write_all(write).unwrap();
    mmap.flush().unwrap();

    file.read_exact(&mut read).unwrap();
    assert_eq!(write, &read);
  }

  #[test]
  fn flush_range() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(128).unwrap();
    let write = b"abc123";

    let mut mmap = unsafe {
      MmapOptions::new()
        .offset(2)
        .len(write.len())
        .map_mut(&file)
        .unwrap()
    };
    (&mut mmap[..]).write_all(write).unwrap();
    mmap.flush_async_range(0, write.len()).unwrap();
    mmap.flush_range(0, write.len()).unwrap();
  }

  #[test]
  fn flush_range_rejects_out_of_bounds() {
    let mmap = MmapMut::map_anon(128).unwrap();

    let err = mmap.flush_range(0, 129).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);

    let err = mmap.flush_range(64, 65).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);

    let err = mmap.flush_range(usize::MAX, 1).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);

    let err = mmap.flush_async_range(0, 129).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);

    // An offset just past map_len is rejected even when len == 0.
    let err = mmap.flush_range(129, 0).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);

    // Exact-fit boundary is accepted as a full-range flush.
    mmap.flush_range(0, 128).unwrap();

    // Zero-length ranges are no-ops and MUST NOT reach the backend — on
    // Windows `FlushViewOfFile(ptr, 0)` is documented to flush from the
    // base to the end of the mapping, and `ptr.add(map_len)` is one past
    // the mapped view even if the `usize` arithmetic is in range.
    mmap.flush_range(128, 0).unwrap();
    mmap.flush_range(64, 0).unwrap();
    mmap.flush_range(0, 0).unwrap();
    mmap.flush_async_range(128, 0).unwrap();
  }

  #[test]
  fn raw_flush_range_rejects_out_of_bounds() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap_raw_range");
    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(64).unwrap();

    let mmap = MmapRaw::map_raw(&file).unwrap();
    let err = mmap.flush_range(0, 65).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
    let err = mmap.flush_async_range(usize::MAX, 1).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
  }

  #[test]
  #[cfg(unix)]
  fn advise_range_rejects_out_of_bounds() {
    let mmap = MmapMut::map_anon(128).unwrap();
    let err = mmap.advise_range(Advice::Normal, 0, 129).unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
  }

  #[test]
  fn map_copy() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let mut file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(128).unwrap();

    let nulls = b"\0\0\0\0\0\0";
    let write = b"abc123";
    let mut read = [0u8; 6];

    let mut mmap = unsafe { MmapOptions::new().map_copy(&file).unwrap() };

    (&mut mmap[..]).write_all(write).unwrap();
    mmap.flush().unwrap();

    // The mmap contains the write
    (&mmap[..]).read_exact(&mut read).unwrap();
    assert_eq!(write, &read);

    // The file does not contain the write
    file.read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);

    // another mmap does not contain the write
    let mmap2 = unsafe { MmapOptions::new().map(&file).unwrap() };
    (&mmap2[..]).read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);
  }

  #[test]
  fn map_copy_read_only() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(128).unwrap();

    let nulls = b"\0\0\0\0\0\0";
    let mut read = [0u8; 6];

    let mmap = unsafe { MmapOptions::new().map_copy_read_only(&file).unwrap() };
    (&mmap[..]).read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);

    let mmap2 = unsafe { MmapOptions::new().map(&file).unwrap() };
    (&mmap2[..]).read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);
  }

  #[test]
  fn map_offset() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();

    let offset = u64::from(u32::MAX) + 2;
    let len = 5432;
    file.set_len(offset + len as u64).unwrap();

    // Check inferred length mmap.
    let mmap = unsafe { MmapOptions::new().offset(offset).map_mut(&file).unwrap() };
    assert_eq!(len, mmap.len());

    // Check explicit length mmap.
    let mut mmap = unsafe {
      MmapOptions::new()
        .offset(offset)
        .len(len)
        .map_mut(&file)
        .unwrap()
    };
    assert_eq!(len, mmap.len());

    let zeros = vec![0; len];
    let incr: Vec<_> = (0..len).map(|i| i as u8).collect();

    // check that the mmap is empty
    assert_eq!(&zeros[..], &mmap[..]);

    // write values into the mmap
    (&mut mmap[..]).write_all(&incr[..]).unwrap();

    // read values back
    assert_eq!(&incr[..], &mmap[..]);
  }

  #[test]
  fn index() {
    let mut mmap = MmapMut::map_anon(128).unwrap();
    mmap[0] = 42;
    assert_eq!(42, mmap[0]);
  }

  #[test]
  fn sync_send() {
    fn is_sync_send<T>(_val: T)
    where
      T: Sync + Send,
    {
    }

    let mmap = MmapMut::map_anon(129).unwrap();
    is_sync_send(mmap);
  }

  #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
  fn jit_x86(mut mmap: MmapMut) {
    mmap[0] = 0xB8; // mov eax, 0xAB
    mmap[1] = 0xAB;
    mmap[2] = 0x00;
    mmap[3] = 0x00;
    mmap[4] = 0x00;
    mmap[5] = 0xC3; // ret

    let mmap = mmap.make_exec().expect("make_exec");

    let jitfn: extern "C" fn() -> u8 = unsafe { mem::transmute(mmap.as_ptr()) };
    assert_eq!(jitfn(), 0xab);
  }

  #[test]
  #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
  fn jit_x86_anon() {
    jit_x86(MmapMut::map_anon(4096).unwrap());
  }

  #[test]
  #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
  fn jit_x86_file() {
    let tempdir = tempfile::tempdir().unwrap();
    let mut options = OpenOptions::new();
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);

    let file = options
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(tempdir.path().join("jit_x86"))
      .expect("open");

    file.set_len(4096).expect("set_len");
    jit_x86(unsafe { MmapMut::map_mut(&file).expect("map_mut") });
  }

  #[test]
  fn mprotect_file() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let mut options = OpenOptions::new();
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);

    let mut file = options
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .expect("open");
    file.set_len(256_u64).expect("set_len");

    let mmap = unsafe { MmapMut::map_mut(&file).expect("map_mut") };

    let mmap = mmap.make_read_only().expect("make_read_only");
    let mut mmap = mmap.make_mut().expect("make_mut");

    let write = b"abc123";
    let mut read = [0u8; 6];

    (&mut mmap[..]).write_all(write).unwrap();
    mmap.flush().unwrap();

    // The mmap contains the write
    (&mmap[..]).read_exact(&mut read).unwrap();
    assert_eq!(write, &read);

    // The file should contain the write
    file.read_exact(&mut read).unwrap();
    assert_eq!(write, &read);

    // another mmap should contain the write
    let mmap2 = unsafe { MmapOptions::new().map(&file).unwrap() };
    (&mmap2[..]).read_exact(&mut read).unwrap();
    assert_eq!(write, &read);

    let mmap = mmap.make_exec().expect("make_exec");

    drop(mmap);
  }

  #[test]
  fn mprotect_copy() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap");

    let mut options = OpenOptions::new();
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);

    let mut file = options
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .expect("open");
    file.set_len(256_u64).expect("set_len");

    let mmap = unsafe { MmapOptions::new().map_copy(&file).expect("map_mut") };

    let mmap = mmap.make_read_only().expect("make_read_only");
    let mut mmap = mmap.make_mut().expect("make_mut");

    let nulls = b"\0\0\0\0\0\0";
    let write = b"abc123";
    let mut read = [0u8; 6];

    (&mut mmap[..]).write_all(write).unwrap();
    mmap.flush().unwrap();

    // The mmap contains the write
    (&mmap[..]).read_exact(&mut read).unwrap();
    assert_eq!(write, &read);

    // The file does not contain the write
    file.read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);

    // another mmap does not contain the write
    let mmap2 = unsafe { MmapOptions::new().map(&file).unwrap() };
    (&mmap2[..]).read_exact(&mut read).unwrap();
    assert_eq!(nulls, &read);

    let mmap = mmap.make_exec().expect("make_exec");

    drop(mmap);
  }

  #[test]
  fn mprotect_anon() {
    let mmap = MmapMut::map_anon(256).expect("map_mut");

    let mmap = mmap.make_read_only().expect("make_read_only");
    let mmap = mmap.make_mut().expect("make_mut");
    let mmap = mmap.make_exec().expect("make_exec");
    drop(mmap);
  }

  #[test]
  fn raw() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmapraw");

    let mut options = OpenOptions::new();
    let mut file = options
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .expect("open");
    file.write_all(b"abc123").unwrap();
    let mmap = MmapOptions::new().map_raw(&file).unwrap();
    assert_eq!(mmap.len(), 6);
    assert!(!mmap.as_ptr().is_null());
    assert_eq!(unsafe { std::ptr::read(mmap.as_ptr()) }, b'a');
  }

  #[test]
  fn raw_read_only() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmaprawro");

    File::create(&path).unwrap().write_all(b"abc123").unwrap();

    let mmap = MmapOptions::new()
      .map_raw_read_only(File::open(&path).unwrap())
      .unwrap();

    assert_eq!(mmap.len(), 6);
    assert!(!mmap.as_ptr().is_null());
    assert_eq!(unsafe { std::ptr::read(mmap.as_ptr()) }, b'a');
  }

  /// Something that relies on StableDeref
  #[test]
  #[cfg(feature = "stable_deref_trait")]
  fn owning_ref() {
    let mut map = MmapMut::map_anon(128).unwrap();
    map[10] = 42;
    let owning = owning_ref::OwningRef::new(map);
    let sliced = owning.map(|map| &map[10..20]);
    assert_eq!(42, sliced[0]);

    let map = sliced.into_owner().make_read_only().unwrap();
    let owning = owning_ref::OwningRef::new(map);
    let sliced = owning.map(|map| &map[10..20]);
    assert_eq!(42, sliced[0]);
  }

  #[test]
  #[cfg(unix)]
  fn advise() {
    let expected_len = 128;
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap_advise");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();

    file.set_len(expected_len as u64).unwrap();

    // Test MmapMut::advise
    let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    mmap
      .advise(Advice::Random)
      .expect("mmap advising should be supported on unix");

    let len = mmap.len();
    assert_eq!(expected_len, len);

    let zeros = vec![0; len];
    let incr: Vec<u8> = (0..len as u8).collect();

    // check that the mmap is empty
    assert_eq!(&zeros[..], &mmap[..]);

    mmap
      .advise_range(Advice::Sequential, 0, mmap.len())
      .expect("mmap advising should be supported on unix");

    // write values into the mmap
    (&mut mmap[..]).write_all(&incr[..]).unwrap();

    // read values back
    assert_eq!(&incr[..], &mmap[..]);

    // Set advice and Read from the read-only map
    let mmap = unsafe { Mmap::map(&file).unwrap() };

    mmap
      .advise(Advice::Random)
      .expect("mmap advising should be supported on unix");

    // read values back
    assert_eq!(&incr[..], &mmap[..]);
  }

  #[test]
  #[cfg(target_os = "linux")]
  fn advise_writes_unsafely() {
    let page_size = rustix::param::page_size();

    let mut mmap = MmapMut::map_anon(page_size).unwrap();
    mmap.as_mut().fill(255);
    let mmap = mmap.make_read_only().unwrap();

    let a = mmap.as_ref()[0];
    unsafe {
      mmap
        .unchecked_advise(crate::UncheckedAdvice::DontNeed)
        .unwrap();
    }
    let b = mmap.as_ref()[0];

    assert_eq!(a, 255);
    assert_eq!(b, 0);
  }

  #[test]
  #[cfg(target_os = "linux")]
  fn advise_writes_unsafely_to_part_of_map() {
    let page_size = rustix::param::page_size();

    let mut mmap = MmapMut::map_anon(2 * page_size).unwrap();
    mmap.as_mut().fill(255);
    let mmap = mmap.make_read_only().unwrap();

    let a = mmap.as_ref()[0];
    let b = mmap.as_ref()[page_size];
    unsafe {
      mmap
        .unchecked_advise_range(crate::UncheckedAdvice::DontNeed, page_size, page_size)
        .unwrap();
    }
    let c = mmap.as_ref()[0];
    let d = mmap.as_ref()[page_size];

    assert_eq!(a, 255);
    assert_eq!(b, 255);
    assert_eq!(c, 255);
    assert_eq!(d, 0);
  }

  /// Returns true if a non-zero amount of memory is locked.
  #[cfg(target_os = "linux")]
  fn is_locked() -> bool {
    let status =
      &std::fs::read_to_string("/proc/self/status").expect("/proc/self/status should be available");
    for line in status.lines() {
      if line.starts_with("VmLck:") {
        let numbers = line.replace(|c: char| !c.is_ascii_digit(), "");
        return numbers != "0";
      }
    }
    panic!("cannot get VmLck information")
  }

  #[test]
  #[cfg(unix)]
  fn lock() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap_lock");

    let file = OpenOptions::new()
      .read(true)
      .write(true)
      .create(true)
      .truncate(true)
      .open(path)
      .unwrap();
    file.set_len(128).unwrap();

    let mmap = unsafe { Mmap::map(&file).unwrap() };
    #[cfg(target_os = "linux")]
    assert!(!is_locked());

    mmap.lock().expect("mmap lock should be supported on unix");
    #[cfg(target_os = "linux")]
    assert!(is_locked());

    mmap
      .lock()
      .expect("mmap lock again should not cause problems");
    #[cfg(target_os = "linux")]
    assert!(is_locked());

    mmap
      .unlock()
      .expect("mmap unlock should be supported on unix");
    #[cfg(target_os = "linux")]
    assert!(!is_locked());

    mmap
      .unlock()
      .expect("mmap unlock again should not cause problems");
    #[cfg(target_os = "linux")]
    assert!(!is_locked());
  }

  #[test]
  #[cfg(target_os = "linux")]
  fn remap_grow() {
    use crate::RemapOptions;

    let initial_len = 128;
    let final_len = 2000;

    let zeros = vec![0u8; final_len];
    let incr: Vec<u8> = (0..final_len).map(|v| v as u8).collect();

    let file = tempfile::tempfile().unwrap();
    file.set_len(final_len as u64).unwrap();

    let mut mmap = unsafe { MmapOptions::new().len(initial_len).map_mut(&file).unwrap() };
    assert_eq!(mmap.len(), initial_len);
    assert_eq!(&mmap[..], &zeros[..initial_len]);

    unsafe {
      mmap
        .remap(final_len, RemapOptions::new().may_move(true))
        .unwrap();
    }

    // The size should have been updated
    assert_eq!(mmap.len(), final_len);

    // Should still be all zeros
    assert_eq!(&mmap[..], &zeros);

    // Write out to the whole expanded slice.
    mmap.copy_from_slice(&incr);
  }

  #[test]
  #[cfg(target_os = "linux")]
  fn remap_shrink() {
    use crate::RemapOptions;

    let initial_len = 20000;
    let final_len = 400;

    let incr: Vec<u8> = (0..final_len).map(|v| v as u8).collect();

    let file = tempfile::tempfile().unwrap();
    file.set_len(initial_len as u64).unwrap();

    let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    assert_eq!(mmap.len(), initial_len);

    unsafe { mmap.remap(final_len, RemapOptions::new()).unwrap() };
    assert_eq!(mmap.len(), final_len);

    // Check that the mmap is still writable along the slice length
    mmap.copy_from_slice(&incr);
  }

  #[test]
  #[cfg(target_os = "linux")]
  #[cfg(target_pointer_width = "32")]
  fn remap_len_overflow() {
    use crate::RemapOptions;

    let file = tempfile::tempfile().unwrap();
    file.set_len(1024).unwrap();
    let mut mmap = unsafe { MmapOptions::new().len(1024).map(&file).unwrap() };

    let res = unsafe { mmap.remap(0x80000000, RemapOptions::new().may_move(true)) };
    assert_eq!(
      res.unwrap_err().to_string(),
      "memory map length overflows isize"
    );

    assert_eq!(mmap.len(), 1024);
  }

  #[test]
  #[cfg(target_os = "linux")]
  fn remap_with_offset() {
    use crate::RemapOptions;

    let offset = 77;
    let initial_len = 128;
    let final_len = 2000;

    let zeros = vec![0u8; final_len];
    let incr: Vec<u8> = (0..final_len).map(|v| v as u8).collect();

    let file = tempfile::tempfile().unwrap();
    file.set_len(final_len as u64 + offset).unwrap();

    let mut mmap = unsafe {
      MmapOptions::new()
        .len(initial_len)
        .offset(offset)
        .map_mut(&file)
        .unwrap()
    };
    assert_eq!(mmap.len(), initial_len);
    assert_eq!(&mmap[..], &zeros[..initial_len]);

    unsafe {
      mmap
        .remap(final_len, RemapOptions::new().may_move(true))
        .unwrap();
    }

    // The size should have been updated
    assert_eq!(mmap.len(), final_len);

    // Should still be all zeros
    assert_eq!(&mmap[..], &zeros);

    // Write out to the whole expanded slice.
    mmap.copy_from_slice(&incr);
  }

  // ---------------------------------------------------------------------
  // Coverage tests
  //
  // The suite below targets paths that the existing tests skip:
  // `MmapOptions` builder setters, `MmapRaw`'s full API, `AsRef`/`AsMut`/
  // `Debug` impls, the `populate()` + `no_reserve_swap()` branches of
  // every `MmapInner::map_*` variant, `Advice::is_supported` per-variant
  // checks on Linux, and the Darwin-specific `Advice`/`UncheckedAdvice`
  // values on Apple targets.
  // ---------------------------------------------------------------------

  /// Exercises the `MmapOptions` builder setters so their bodies count as
  /// covered. The setters just flip internal flags; they do not perform
  /// any system call themselves.
  #[test]
  fn mmap_options_builder_setters_coverage() {
    let mut opts = MmapOptions::new();
    opts
      .offset(0)
      .len(4096)
      .stack()
      .huge(Some(21))
      .huge(None)
      .populate()
      .no_reserve_swap();
    // If we reach this point the setters returned `&mut Self` correctly.
  }

  /// `get_len` returns an `InvalidData` error when the requested offset
  /// sits past the end of the file.
  #[test]
  fn map_options_offset_past_file_len() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("small");
    File::create(&path).unwrap().write_all(b"tiny").unwrap();
    let file = File::open(&path).unwrap();
    let err = unsafe { MmapOptions::new().offset(1024).map(&file) }.unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
  }

  /// Exercises `AsRef`/`AsMut`/`Debug` on all three map types.
  #[test]
  fn as_ref_as_mut_debug_impls() {
    let mut m = MmapMut::map_anon(32).unwrap();
    // `AsMut<[u8]>` then mutate via the slice
    <MmapMut as AsMut<[u8]>>::as_mut(&mut m)[0] = 7;
    // `AsRef<[u8]>` read back
    assert_eq!(<MmapMut as AsRef<[u8]>>::as_ref(&m)[0], 7);
    let dbg = format!("{m:?}");
    assert!(dbg.starts_with("MmapMut"));

    let mmap = m.make_read_only().unwrap();
    assert_eq!(<Mmap as AsRef<[u8]>>::as_ref(&mmap).len(), 32);
    let dbg = format!("{mmap:?}");
    assert!(dbg.starts_with("Mmap"));

    let raw: MmapRaw = mmap.into();
    let dbg = format!("{raw:?}");
    assert!(dbg.starts_with("MmapRaw"));
  }

  /// Exercises the full `MmapRaw` API surface: both pointer accessors,
  /// every flush variant, and (on unix) lock/unlock + every advise
  /// variant.
  #[test]
  fn mmap_raw_api_coverage() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("raw_api");
    let mut options = OpenOptions::new();
    options.read(true).write(true).create(true).truncate(true);
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);
    let file = options.open(&path).unwrap();
    file.set_len(256).unwrap();

    // Exercise both constructor entry points.
    let _ = MmapRaw::map_raw(&file).unwrap();
    let mmap = MmapOptions::new().map_raw(&file).unwrap();

    assert_eq!(mmap.len(), 256);
    assert!(!mmap.as_ptr().is_null());
    assert!(!mmap.as_mut_ptr().is_null());

    mmap.flush().unwrap();
    mmap.flush_async().unwrap();
    mmap.flush_range(0, 64).unwrap();
    mmap.flush_async_range(64, 64).unwrap();

    #[cfg(unix)]
    {
      mmap.advise(Advice::Random).unwrap();
      mmap
        .advise_range(Advice::Sequential, 0, mmap.len())
        .unwrap();
      unsafe {
        mmap.unchecked_advise(UncheckedAdvice::DontNeed).unwrap();
      }
      unsafe {
        mmap
          .unchecked_advise_range(UncheckedAdvice::DontNeed, 0, mmap.len())
          .unwrap();
      }
      mmap.lock().unwrap();
      mmap.unlock().unwrap();
    }

    // Drive the read-only entry point too so its body is counted.
    let ro = MmapOptions::new()
      .map_raw_read_only(File::open(&path).unwrap())
      .unwrap();
    assert_eq!(ro.len(), 256);
  }

  /// Exercises `flush_async` and `flush_async_range` on `MmapMut`.
  #[test]
  fn mmap_mut_flush_async_coverage() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("flush_async");
    let mut options = OpenOptions::new();
    options.read(true).write(true).create(true).truncate(true);
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);
    let file = options.open(&path).unwrap();
    file.set_len(128).unwrap();

    let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
    mmap[0] = 1;
    mmap.flush_async().unwrap();
    mmap.flush_async_range(0, 16).unwrap();
  }

  /// Exercises `MmapMut::advise_range` and the `unchecked_advise` family.
  #[test]
  #[cfg(unix)]
  fn mmap_mut_advise_coverage() {
    let mmap = MmapMut::map_anon(128).unwrap();
    mmap.advise_range(Advice::Random, 0, 128).unwrap();
    unsafe {
      mmap.unchecked_advise(UncheckedAdvice::DontNeed).unwrap();
    }
    unsafe {
      mmap
        .unchecked_advise_range(UncheckedAdvice::DontNeed, 0, 128)
        .unwrap();
    }
  }

  /// Drives `populate()` and `no_reserve_swap()` through every
  /// file-backed `map_*` variant plus the anonymous path. On non-Linux
  /// targets `MAP_POPULATE` is a no-op, and `MAP_NORESERVE` is ignored
  /// on platforms where rustix doesn't expose it, so these calls are
  /// safe cross-platform smoke tests of the flag plumbing.
  #[test]
  fn populate_no_reserve_map_variants() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("variants");
    let mut options = OpenOptions::new();
    options.read(true).write(true).create(true).truncate(true);
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);
    let file = options.open(&path).unwrap();
    file.set_len(4096).unwrap();

    unsafe {
      let _m = MmapOptions::new()
        .populate()
        .no_reserve_swap()
        .map(&file)
        .unwrap();
      let _m = MmapOptions::new()
        .populate()
        .no_reserve_swap()
        .map_mut(&file)
        .unwrap();
      let _m = MmapOptions::new()
        .populate()
        .no_reserve_swap()
        .map_copy(&file)
        .unwrap();
      let _m = MmapOptions::new()
        .populate()
        .no_reserve_swap()
        .map_copy_read_only(&file)
        .unwrap();
    }

    // Anonymous map with stack + populate + no_reserve set. `huge()` is
    // deliberately omitted because it requires huge-page reservations
    // that may not be available on the CI host.
    let _m = MmapOptions::new()
      .stack()
      .populate()
      .no_reserve_swap()
      .len(4096)
      .map_anon()
      .unwrap();
  }

  /// Drives every Linux-only `Advice` / `UncheckedAdvice` variant
  /// through `is_supported`. The method performs a probe `madvise`
  /// against `NULL/0` so it has no memory effect regardless of the
  /// kernel's answer.
  #[test]
  #[cfg(target_os = "linux")]
  fn advise_is_supported_linux_variants() {
    for a in [
      Advice::Normal,
      Advice::Random,
      Advice::Sequential,
      Advice::WillNeed,
      Advice::DontFork,
      Advice::DoFork,
      Advice::Mergeable,
      Advice::Unmergeable,
      Advice::HugePage,
      Advice::NoHugePage,
      Advice::DontDump,
      Advice::DoDump,
      Advice::HwPoison,
      Advice::PopulateRead,
      Advice::PopulateWrite,
    ] {
      // We don't care about the result; we just want the code path
      // exercised. `HwPoison` in particular requires privileges.
      let _ = a.is_supported();
    }

    for a in [
      UncheckedAdvice::DontNeed,
      UncheckedAdvice::Free,
      UncheckedAdvice::Remove,
    ] {
      let _ = a.is_supported();
    }
  }

  /// Exercises every Apple advice variant so each arm of the Darwin
  /// `to_raw` match gets counted. The Darwin-specific values route
  /// through `libc::madvise` (not rustix) because rustix v1 does not
  /// model them. Non-POSIX variants may reject read-only or
  /// non-anonymous mappings; we only care that each arm executes.
  #[test]
  #[cfg(target_vendor = "apple")]
  fn apple_advise_variants() {
    let mut m = MmapMut::map_anon(4096).unwrap();
    m.as_mut().fill(1);
    let m = m.make_read_only().unwrap();

    for a in [
      Advice::Normal,
      Advice::Random,
      Advice::Sequential,
      Advice::WillNeed,
      Advice::ZeroWiredPages,
    ] {
      let _ = m.advise(a);
    }
    unsafe {
      let _ = m.unchecked_advise(UncheckedAdvice::Free);
      let _ = m.unchecked_advise(UncheckedAdvice::FreeReusable);
      let _ = m.unchecked_advise(UncheckedAdvice::FreeReuse);
      let _ = m.unchecked_advise(UncheckedAdvice::DontNeed);
    }
  }

  /// Covers `MmapInner::map_exec` and its flag-expansion branches.
  /// Whether the kernel actually grants `PROT_EXEC` on a plain file is
  /// platform- and policy-dependent, so we accept either success or an
  /// OS error: the goal is to execute the code path in `map_exec`.
  #[test]
  fn map_exec_coverage() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("mmap_exec");
    let mut options = OpenOptions::new();
    options.read(true).write(true).create(true).truncate(true);
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);
    let file = options.open(&path).unwrap();
    file.set_len(4096).unwrap();

    let file = File::open(&path).unwrap();
    // Two calls: one with populate + no_reserve_swap set (covers the
    // `true` arms of the flag match), one with defaults (covers the
    // `MapFlags::empty()` arms).
    let _ = unsafe {
      MmapOptions::new()
        .populate()
        .no_reserve_swap()
        .map_exec(&file)
    };
    let _ = unsafe { MmapOptions::new().map_exec(&file) };
  }

  /// Covers `MmapMut::lock` / `unlock` and `From<MmapMut> for MmapRaw`.
  #[test]
  #[cfg(unix)]
  fn mmap_mut_lock_and_raw_conversion() {
    let mut mmap = MmapMut::map_anon(4096).unwrap();
    mmap[0] = 42;
    mmap.lock().unwrap();
    mmap.unlock().unwrap();

    let raw: MmapRaw = mmap.into();
    assert_eq!(raw.len(), 4096);
  }

  /// Covers `Mmap::advise_range` and `Mmap::unchecked_advise_range`.
  #[test]
  #[cfg(unix)]
  fn mmap_advise_range_coverage() {
    let mmap = MmapMut::map_anon(4096).unwrap().make_read_only().unwrap();
    mmap.advise_range(Advice::Random, 0, 4096).unwrap();
    unsafe {
      mmap
        .unchecked_advise_range(UncheckedAdvice::DontNeed, 0, 4096)
        .unwrap();
    }
  }

  /// Covers the `huge.is_some()` branch of `map_anon` flag plumbing.
  /// An actual `MAP_HUGETLB` allocation requires huge-page reservations
  /// the CI host may not have, so any OS error is acceptable — we only
  /// need the `huge` arm of the flag match to execute.
  #[test]
  fn map_anon_huge_flag_coverage() {
    let _ = MmapOptions::new()
      .huge(Some(21))
      .len(2 * 1024 * 1024)
      .map_anon();
  }

  /// Exercises `validate_len` rejecting lengths that don't fit in
  /// `isize`. On a 64-bit target only values above `isize::MAX` (half
  /// the `u64` range) trigger the check; on 32-bit it fires earlier.
  #[test]
  fn validate_len_overflow() {
    let tempdir = tempfile::tempdir().unwrap();
    let path = tempdir.path().join("small");
    File::create(&path).unwrap().write_all(b"hi").unwrap();
    let file = File::open(&path).unwrap();

    // `usize::MAX` is `u64::MAX` on 64-bit targets, well past `isize::MAX`.
    let err = unsafe { MmapOptions::new().len(usize::MAX).map(&file) }.unwrap_err();
    assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
  }

  /// Exercises `MmapRaw::remap`.
  #[test]
  #[cfg(target_os = "linux")]
  fn mmap_raw_remap_grow() {
    use crate::RemapOptions;
    let file = tempfile::tempfile().unwrap();
    file.set_len(8192).unwrap();
    let mut mmap = MmapOptions::new().len(4096).map_raw(&file).unwrap();
    assert_eq!(mmap.len(), 4096);
    unsafe {
      mmap
        .remap(8192, RemapOptions::new().may_move(true))
        .unwrap();
    }
    assert_eq!(mmap.len(), 8192);
  }
}