Struct memmap2::Advice

source ·

pub struct Advice(/* private fields */);

Expand description

Values supported by Mmap::advise and MmapMut::advise functions. See madvise() map page.

Implementations§

source §

impl Advice

source

pub fn normal() -> Self

MADV_NORMAL

No special treatment. This is the default.

source

pub fn random() -> Self

MADV_RANDOM

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

source

pub fn sequential() -> Self

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.)

source

pub fn will_need() -> Self

MADV_WILLNEED

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

source

pub unsafe fn dont_need() -> Self

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.

source

pub unsafe fn free() -> Self

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.

source

pub fn zero_wired_pages() -> Self

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.

source

pub unsafe fn free_reusable() -> Self

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.

source

pub unsafe fn free_reuse() -> Self

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.