memmapix 0.8.0

/// The value fed to the platform's `madvise` call.
///
/// rustix v1 does not model the Darwin-specific advice values this crate
/// exposes (`MADV_FREE`, `MADV_FREE_REUSABLE`, `MADV_FREE_REUSE`,
/// `MADV_ZERO_WIRED_PAGES`), so Apple targets carry a raw `c_int`
/// (always `i32` on Apple) and route through `libc::madvise`. Every other
/// unix platform carries a `rustix::mm::Advice` and routes through
/// `rustix::mm::madvise`. Each platform populates exactly one variant.
pub(crate) enum RawAdvice {
  #[cfg(target_vendor = "apple")]
  Libc(i32),

  #[cfg(not(target_vendor = "apple"))]
  Rustix(rustix::mm::Advice),
}

/// Values supported by [`Mmap::advise`][crate::Mmap::advise] and [`MmapMut::advise`][crate::MmapMut::advise] functions.
///
/// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub enum Advice {
  /// **MADV_NORMAL**
  ///
  /// No special treatment.  This is the default.
  Normal,

  /// **MADV_RANDOM**
  ///
  /// Expect page references in random order.  (Hence, read
  /// ahead may be less useful than normally.)
  Random,

  /// **MADV_SEQUENTIAL**
  ///
  /// Expect page references in sequential order.  (Hence, pages
  /// in the given range can be aggressively read ahead, and may
  /// be freed soon after they are accessed.)
  Sequential,

  /// **MADV_WILLNEED**
  ///
  /// Expect access in the near future.  (Hence, it might be a
  /// good idea to read some pages ahead.)
  WillNeed,

  /// **MADV_DONTFORK** - Linux only (since Linux 2.6.16)
  ///
  /// Do not make the pages in this range available to the child
  /// after a fork(2).  This is useful to prevent copy-on-write
  /// semantics from changing the physical location of a page if
  /// the parent writes to it after a fork(2).  (Such page
  /// relocations cause problems for hardware that DMAs into the
  /// page.)
  #[cfg(target_os = "linux")]
  DontFork,

  /// **MADV_DOFORK** - Linux only (since Linux 2.6.16)
  ///
  /// Undo the effect of MADV_DONTFORK, restoring the default
  /// behavior, whereby a mapping is inherited across fork(2).
  #[cfg(target_os = "linux")]
  DoFork,

  /// **MADV_MERGEABLE** - Linux only (since Linux 2.6.32)
  ///
  /// Enable Kernel Samepage Merging (KSM) for the pages in the
  /// range specified by addr and length.  The kernel regularly
  /// scans those areas of user memory that have been marked as
  /// mergeable, looking for pages with identical content.
  /// These are replaced by a single write-protected page (which
  /// is automatically copied if a process later wants to update
  /// the content of the page).  KSM merges only private
  /// anonymous pages (see mmap(2)).
  ///
  /// The KSM feature is intended for applications that generate
  /// many instances of the same data (e.g., virtualization
  /// systems such as KVM).  It can consume a lot of processing
  /// power; use with care.  See the Linux kernel source file
  /// Documentation/admin-guide/mm/ksm.rst for more details.
  ///
  /// The MADV_MERGEABLE and MADV_UNMERGEABLE operations are
  /// available only if the kernel was configured with
  /// CONFIG_KSM.
  #[cfg(target_os = "linux")]
  Mergeable,

  /// **MADV_UNMERGEABLE** - Linux only (since Linux 2.6.32)
  ///
  /// Undo the effect of an earlier MADV_MERGEABLE operation on
  /// the specified address range; KSM unmerges whatever pages
  /// it had merged in the address range specified by addr and
  /// length.
  #[cfg(target_os = "linux")]
  Unmergeable,

  /// **MADV_HUGEPAGE** - Linux only (since Linux 2.6.38)
  ///
  /// Enable Transparent Huge Pages (THP) for pages in the range
  /// specified by addr and length.  Currently, Transparent Huge
  /// Pages work only with private anonymous pages (see
  /// mmap(2)).  The kernel will regularly scan the areas marked
  /// as huge page candidates to replace them with huge pages.
  /// The kernel will also allocate huge pages directly when the
  /// region is naturally aligned to the huge page size (see
  /// posix_memalign(2)).
  ///
  /// This feature is primarily aimed at applications that use
  /// large mappings of data and access large regions of that
  /// memory at a time (e.g., virtualization systems such as
  /// QEMU).  It can very easily waste memory (e.g., a 2 MB
  /// mapping that only ever accesses 1 byte will result in 2 MB
  /// of wired memory instead of one 4 KB page).  See the Linux
  /// kernel source file
  /// Documentation/admin-guide/mm/transhuge.rst for more
  /// details.
  ///
  /// Most common kernels configurations provide MADV_HUGEPAGE-
  /// style behavior by default, and thus MADV_HUGEPAGE is
  /// normally not necessary.  It is mostly intended for
  /// embedded systems, where MADV_HUGEPAGE-style behavior may
  /// not be enabled by default in the kernel.  On such systems,
  /// this flag can be used in order to selectively enable THP.
  /// Whenever MADV_HUGEPAGE is used, it should always be in
  /// regions of memory with an access pattern that the
  /// developer knows in advance won't risk to increase the
  /// memory footprint of the application when transparent
  /// hugepages are enabled.
  ///
  /// The MADV_HUGEPAGE and MADV_NOHUGEPAGE operations are
  /// available only if the kernel was configured with
  /// CONFIG_TRANSPARENT_HUGEPAGE.
  #[cfg(target_os = "linux")]
  HugePage,

  /// **MADV_NOHUGEPAGE** - Linux only (since Linux 2.6.38)
  ///
  /// Ensures that memory in the address range specified by addr
  /// and length will not be backed by transparent hugepages.
  #[cfg(target_os = "linux")]
  NoHugePage,

  /// **MADV_DONTDUMP** - Linux only (since Linux 3.4)
  ///
  /// Exclude from a core dump those pages in the range
  /// specified by addr and length.  This is useful in
  /// applications that have large areas of memory that are
  /// known not to be useful in a core dump.  The effect of
  /// **MADV_DONTDUMP** takes precedence over the bit mask that is
  /// set via the `/proc/[pid]/coredump_filter` file (see
  /// core(5)).
  #[cfg(target_os = "linux")]
  DontDump,

  /// **MADV_DODUMP** - Linux only (since Linux 3.4)
  ///
  /// Undo the effect of an earlier MADV_DONTDUMP.
  #[cfg(target_os = "linux")]
  DoDump,

  /// **MADV_HWPOISON** - Linux only (since Linux 2.6.32)
  ///
  /// Poison the pages in the range specified by addr and length
  /// and handle subsequent references to those pages like a
  /// hardware memory corruption.  This operation is available
  /// only for privileged (CAP_SYS_ADMIN) processes.  This
  /// operation may result in the calling process receiving a
  /// SIGBUS and the page being unmapped.
  ///
  /// This feature is intended for testing of memory error-
  /// handling code; it is available only if the kernel was
  /// configured with CONFIG_MEMORY_FAILURE.
  #[cfg(target_os = "linux")]
  HwPoison,

  /// **MADV_POPULATE_READ** - Linux only (since Linux 5.14)
  ///
  /// Populate  (prefault)  page  tables readable, faulting in all
  /// pages in the range just as  if  manually  reading  from  each
  /// page; however, avoid the actual memory access that would have
  /// been performed after handling the fault.
  ///
  /// In contrast to MAP_POPULATE, MADV_POPULATE_READ does not hide
  /// errors,  can  be  applied to (parts of) existing mappings and
  /// will always populate (prefault) page  tables  readable.   One
  /// example  use  case is prefaulting a file mapping, reading all
  /// file content from disk; however, pages won't be  dirtied  and
  /// consequently  won't  have  to  be  written  back to disk when
  /// evicting the pages from memory.
  ///
  /// Depending on the underlying mapping, map the shared zeropage,
  /// preallocate  memory  or  read the underlying file; files with
  /// holes might or might not preallocate blocks.   If  populating
  /// fails, a SIGBUS signal is not generated; instead, an error is
  /// returned.
  ///
  /// If MADV_POPULATE_READ succeeds, all  page  tables  have  been
  /// populated  (prefaulted) readable once.  If MADV_POPULATE_READ
  /// fails, some page tables might have been populated.
  ///
  /// MADV_POPULATE_READ cannot be applied to mappings without read
  /// permissions  and  special  mappings,  for  example,  mappings
  /// marked with kernel-internal flags such as VM_PFNMAP or VM_IO,
  /// or secret memory regions created using memfd_secret(2).
  ///
  /// Note  that with MADV_POPULATE_READ, the process can be killed
  /// at any moment when the system runs out of memory.
  #[cfg(target_os = "linux")]
  PopulateRead,

  /// **MADV_POPULATE_WRITE** - Linux only (since Linux 5.14)
  ///
  /// Populate (prefault) page tables  writable,  faulting  in  all
  /// pages  in  the range just as if manually writing to each each
  /// page; however, avoid the actual memory access that would have
  /// been performed after handling the fault.
  ///
  /// In  contrast  to  MAP_POPULATE,  MADV_POPULATE_WRITE does not
  /// hide errors, can be applied to (parts of)  existing  mappings
  /// and  will  always  populate  (prefault) page tables writable.
  /// One example use case is preallocating  memory,  breaking  any
  /// CoW (Copy on Write).
  ///
  /// Depending  on  the  underlying mapping, preallocate memory or
  /// read the underlying file; files with holes  will  preallocate
  /// blocks.   If  populating fails, a SIGBUS signal is not gener‐
  /// ated; instead, an error is returned.
  ///
  /// If MADV_POPULATE_WRITE succeeds, all page  tables  have  been
  /// populated (prefaulted) writable once.  If MADV_POPULATE_WRITE
  /// fails, some page tables might have been populated.
  ///
  /// MADV_POPULATE_WRITE cannot be  applied  to  mappings  without
  /// write permissions and special mappings, for example, mappings
  /// marked with kernel-internal flags such as VM_PFNMAP or VM_IO,
  /// or secret memory regions created using memfd_secret(2).
  ///
  /// Note that with MADV_POPULATE_WRITE, the process can be killed
  /// at any moment when the system runs out of memory.
  #[cfg(target_os = "linux")]
  PopulateWrite,

  /// **MADV_ZERO_WIRED_PAGES** - Darwin only
  ///
  /// Indicates that the application would like the wired pages in this address range to be
  /// zeroed out if the address range is deallocated without first unwiring the pages (i.e.
  /// a munmap(2) without a preceding munlock(2) or the application quits).  This is used
  /// with `madvise()` system call.
  #[cfg(target_vendor = "apple")]
  ZeroWiredPages,
}

/// Values supported by [`Mmap::unchecked_advise`][crate::Mmap::unchecked_advise] and [`MmapMut::unchecked_advise`][crate::MmapMut::unchecked_advise] functions.
///
/// These flags can be passed to the [madvise (2)][man_page] system call
/// and effects on the mapped pages which are conceptually writes,
/// i.e. the change the observable contents of these pages which
/// implies undefined behaviour if the mapping is still borrowed.
///
/// Hence, these potentially unsafe flags must be used with the unsafe
/// methods and the programmer has to justify that the code
/// does not keep any borrows of the mapping active while the mapped pages
/// are updated by the kernel's memory management subsystem.
///
/// [man_page]: https://man7.org/linux/man-pages/man2/madvise.2.html
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub enum UncheckedAdvice {
  /// **MADV_DONTNEED**
  ///
  /// Do not expect access in the near future.  (For the time
  /// being, the application is finished with the given range,
  /// so the kernel can free resources associated with it.)
  ///
  /// After a successful MADV_DONTNEED operation, the semantics
  /// of memory access in the specified region are changed:
  /// subsequent accesses of pages in the range will succeed,
  /// but will result in either repopulating the memory contents
  /// from the up-to-date contents of the underlying mapped file
  /// (for shared file mappings, shared anonymous mappings, and
  /// shmem-based techniques such as System V shared memory
  /// segments) or zero-fill-on-demand pages for anonymous
  /// private mappings.
  ///
  /// Note that, when applied to shared mappings, MADV_DONTNEED
  /// might not lead to immediate freeing of the pages in the
  /// range.  The kernel is free to delay freeing the pages
  /// until an appropriate moment.  The resident set size (RSS)
  /// of the calling process will be immediately reduced
  /// however.
  ///
  /// **MADV_DONTNEED** cannot be applied to locked pages, Huge TLB
  /// pages, or VM_PFNMAP pages.  (Pages marked with the kernel-
  /// internal VM_PFNMAP flag are special memory areas that are
  /// not managed by the virtual memory subsystem.  Such pages
  /// are typically created by device drivers that map the pages
  /// into user space.)
  ///
  /// # Safety
  ///
  /// Using the returned value with conceptually write to the
  /// mapped pages, i.e. borrowing the mapping when the pages
  /// are freed results in undefined behaviour.
  DontNeed,

  /// **MADV_FREE** - Linux (since Linux 4.5) and Darwin
  ///
  /// The application no longer requires the pages in the range
  /// specified by addr and len.  The kernel can thus free these
  /// pages, but the freeing could be delayed until memory
  /// pressure occurs.  For each of the pages that has been
  /// marked to be freed but has not yet been freed, the free
  /// operation will be canceled if the caller writes into the
  /// page.  After a successful MADV_FREE operation, any stale
  /// data (i.e., dirty, unwritten pages) will be lost when the
  /// kernel frees the pages.  However, subsequent writes to
  /// pages in the range will succeed and then kernel cannot
  /// free those dirtied pages, so that the caller can always
  /// see just written data.  If there is no subsequent write,
  /// the kernel can free the pages at any time.  Once pages in
  /// the range have been freed, the caller will see zero-fill-
  /// on-demand pages upon subsequent page references.
  ///
  /// The MADV_FREE operation can be applied only to private
  /// anonymous pages (see mmap(2)).  In Linux before version
  /// 4.12, when freeing pages on a swapless system, the pages
  /// in the given range are freed instantly, regardless of
  /// memory pressure.
  ///
  /// # Safety
  ///
  /// Using the returned value with conceptually write to the
  /// mapped pages, i.e. borrowing the mapping while the pages
  /// are still being freed results in undefined behaviour.
  #[cfg(any(target_os = "linux", target_vendor = "apple"))]
  Free,

  /// **MADV_REMOVE** - Linux only (since Linux 2.6.16)
  ///
  /// Free up a given range of pages and its associated backing
  /// store.  This is equivalent to punching a hole in the
  /// corresponding byte range of the backing store (see
  /// fallocate(2)).  Subsequent accesses in the specified
  /// address range will see bytes containing zero.
  ///
  /// The specified address range must be mapped shared and
  /// writable.  This flag cannot be applied to locked pages,
  /// Huge TLB pages, or VM_PFNMAP pages.
  ///
  /// In the initial implementation, only tmpfs(5) was supported
  /// **MADV_REMOVE**; but since Linux 3.5, any filesystem which
  /// supports the fallocate(2) FALLOC_FL_PUNCH_HOLE mode also
  /// supports MADV_REMOVE.  Hugetlbfs fails with the error
  /// EINVAL and other filesystems fail with the error
  /// EOPNOTSUPP.
  ///
  /// # Safety
  ///
  /// Using the returned value with conceptually write to the
  /// mapped pages, i.e. borrowing the mapping when the pages
  /// are freed results in undefined behaviour.
  #[cfg(target_os = "linux")]
  Remove,

  /// **MADV_FREE_REUSABLE** - Darwin only
  ///
  /// Behaves like **MADV_FREE**, but the freed pages are accounted for in the RSS of the process.
  ///
  /// # Safety
  ///
  /// Using the returned value with conceptually write to the
  /// mapped pages, i.e. borrowing the mapping while the pages
  /// are still being freed results in undefined behaviour.
  #[cfg(target_vendor = "apple")]
  FreeReusable,

  /// **MADV_FREE_REUSE** - Darwin only
  ///
  /// Marks a memory region previously freed by **MADV_FREE_REUSABLE** as non-reusable, accounts
  /// for the pages in the RSS of the process. Pages that have been freed will be replaced by
  /// zero-filled pages on demand, other pages will be left as is.
  ///
  /// # Safety
  ///
  /// Using the returned value with conceptually write to the
  /// mapped pages, i.e. borrowing the mapping while the pages
  /// are still being freed results in undefined behaviour.
  #[cfg(target_vendor = "apple")]
  FreeReuse,
}

// Future expansion:
// MADV_SOFT_OFFLINE  (since Linux 2.6.33)
// MADV_WIPEONFORK  (since Linux 4.14)
// MADV_KEEPONFORK  (since Linux 4.14)
// MADV_COLD  (since Linux 5.4)
// MADV_PAGEOUT  (since Linux 5.4)

#[cfg(target_vendor = "apple")]
impl Advice {
  pub(crate) fn to_raw(self) -> RawAdvice {
    RawAdvice::Libc(match self {
      Advice::Normal => libc::MADV_NORMAL,
      Advice::Random => libc::MADV_RANDOM,
      Advice::Sequential => libc::MADV_SEQUENTIAL,
      Advice::WillNeed => libc::MADV_WILLNEED,
      Advice::ZeroWiredPages => libc::MADV_ZERO_WIRED_PAGES,
    })
  }
}

#[cfg(not(target_vendor = "apple"))]
impl Advice {
  pub(crate) fn to_raw(self) -> RawAdvice {
    use rustix::mm::Advice as R;
    RawAdvice::Rustix(match self {
      Advice::Normal => R::Normal,
      Advice::Random => R::Random,
      Advice::Sequential => R::Sequential,
      Advice::WillNeed => R::WillNeed,
      #[cfg(target_os = "linux")]
      Advice::DontFork => R::LinuxDontFork,
      #[cfg(target_os = "linux")]
      Advice::DoFork => R::LinuxDoFork,
      #[cfg(target_os = "linux")]
      Advice::Mergeable => R::LinuxMergeable,
      #[cfg(target_os = "linux")]
      Advice::Unmergeable => R::LinuxUnmergeable,
      #[cfg(target_os = "linux")]
      Advice::HugePage => R::LinuxHugepage,
      #[cfg(target_os = "linux")]
      Advice::NoHugePage => R::LinuxNoHugepage,
      #[cfg(target_os = "linux")]
      Advice::DontDump => R::LinuxDontDump,
      #[cfg(target_os = "linux")]
      Advice::DoDump => R::LinuxDoDump,
      #[cfg(target_os = "linux")]
      Advice::HwPoison => R::LinuxHwPoison,
      #[cfg(target_os = "linux")]
      Advice::PopulateRead => R::LinuxPopulateRead,
      #[cfg(target_os = "linux")]
      Advice::PopulateWrite => R::LinuxPopulateWrite,
    })
  }
}

#[cfg(target_vendor = "apple")]
impl UncheckedAdvice {
  pub(crate) fn to_raw(self) -> RawAdvice {
    RawAdvice::Libc(match self {
      UncheckedAdvice::DontNeed => libc::MADV_DONTNEED,
      UncheckedAdvice::Free => libc::MADV_FREE,
      UncheckedAdvice::FreeReusable => libc::MADV_FREE_REUSABLE,
      UncheckedAdvice::FreeReuse => libc::MADV_FREE_REUSE,
    })
  }
}

#[cfg(not(target_vendor = "apple"))]
impl UncheckedAdvice {
  pub(crate) fn to_raw(self) -> RawAdvice {
    use rustix::mm::Advice as R;
    RawAdvice::Rustix(match self {
      // On Linux, prefer the MADV_DONTNEED semantics; elsewhere rustix
      // only offers POSIX_MADV_DONTNEED via `Advice::DontNeed`.
      #[cfg(target_os = "linux")]
      UncheckedAdvice::DontNeed => R::LinuxDontNeed,
      #[cfg(not(target_os = "linux"))]
      UncheckedAdvice::DontNeed => R::DontNeed,
      #[cfg(target_os = "linux")]
      UncheckedAdvice::Free => R::LinuxFree,
      #[cfg(target_os = "linux")]
      UncheckedAdvice::Remove => R::LinuxRemove,
    })
  }
}

#[cfg(target_os = "linux")]
impl Advice {
  /// Performs a runtime check if this advice is supported by the kernel.
  /// Only supported on Linux. See the [`madvise(2)`] man page.
  ///
  /// [`madvise(2)`]: https://man7.org/linux/man-pages/man2/madvise.2.html#VERSIONS
  pub fn is_supported(self) -> bool {
    let RawAdvice::Rustix(advice) = self.to_raw();
    unsafe { rustix::mm::madvise(std::ptr::null_mut(), 0, advice).is_ok() }
  }
}

#[cfg(target_os = "linux")]
impl UncheckedAdvice {
  /// Performs a runtime check if this advice is supported by the kernel.
  /// Only supported on Linux. See the [`madvise(2)`] man page.
  ///
  /// [`madvise(2)`]: https://man7.org/linux/man-pages/man2/madvise.2.html#VERSIONS
  pub fn is_supported(self) -> bool {
    let RawAdvice::Rustix(advice) = self.to_raw();
    unsafe { rustix::mm::madvise(std::ptr::null_mut(), 0, advice).is_ok() }
  }
}

#[cfg(test)]
mod tests {
  #[cfg(target_os = "linux")]
  #[test]
  fn test_is_supported() {
    use super::*;

    assert!(Advice::Normal.is_supported());
    assert!(Advice::Random.is_supported());
    assert!(Advice::Sequential.is_supported());
    assert!(Advice::WillNeed.is_supported());

    assert!(UncheckedAdvice::DontNeed.is_supported());
  }
}