diff options
Diffstat (limited to 'vendor/memmap2/src/advice.rs')
| -rw-r--r-- | vendor/memmap2/src/advice.rs | 216 |
1 files changed, 130 insertions, 86 deletions
diff --git a/vendor/memmap2/src/advice.rs b/vendor/memmap2/src/advice.rs index 0181615ef..4316058fc 100644 --- a/vendor/memmap2/src/advice.rs +++ b/vendor/memmap2/src/advice.rs @@ -1,8 +1,5 @@ -// The use statement is needed for the `cargo docs` -#[allow(unused_imports)] -use crate::{Mmap, MmapMut}; - -/// Values supported by [Mmap::advise] and [MmapMut::advise] functions. +/// 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. #[repr(i32)] #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)] @@ -31,87 +28,6 @@ pub enum Advice { /// good idea to read some pages ahead.) WillNeed = libc::MADV_WILLNEED, - /// **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.) - DontNeed = libc::MADV_DONTNEED, - - // - // The rest are Linux-specific - // - /// **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. - #[cfg(any(target_os = "linux", target_os = "macos", target_os = "ios"))] - Free = libc::MADV_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. - #[cfg(target_os = "linux")] - Remove = libc::MADV_REMOVE, - /// **MADV_DONTFORK** - Linux only (since Linux 2.6.16) /// /// Do not make the pages in this range available to the child @@ -316,10 +232,132 @@ pub enum Advice { /// with madvise() system call. #[cfg(any(target_os = "macos", target_os = "ios"))] ZeroWiredPages = libc::MADV_ZERO_WIRED_PAGES, +} + +/// Values supported by [`Mmap::unsafe_advise`][crate::Mmap::unsafe_advise] and [`MmapMut::unsafe_advise`][crate::MmapMut::unsafe_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 +#[repr(i32)] +#[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 = libc::MADV_DONTNEED, + + // + // The rest are Linux-specific + // + /// **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_os = "macos", target_os = "ios"))] + Free = libc::MADV_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 = libc::MADV_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(any(target_os = "macos", target_os = "ios"))] FreeReusable = libc::MADV_FREE_REUSABLE, @@ -328,6 +366,12 @@ pub enum Advice { /// 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(any(target_os = "macos", target_os = "ios"))] FreeReuse = libc::MADV_FREE_REUSE, } |