Struct PurgeFlags

Source

pub struct PurgeFlags {
    pub force: bool,
    pub reclaim: bool,
}

Expand description

Flags for purge_all_ex (issue #366).

Fields§

§force: bool

Ignore purge_delay and hole-purge pacing, and let a claimed sweep run to completion (MI_PURGE_FORCE). purge_all(true) is this flag set.

§reclaim: bool

Give back every arena of every sub-process that is COMPLETELY free, its metadata included (MI_PURGE_RECLAIM). See PurgeFlags::RECLAIM.

Implementations§

Source §

impl PurgeFlags

Source

pub const NONE: PurgeFlags

Every flag clear: honour the purge pacing options and keep every arena.

Source

MI_PURGE_RECLAIM: also give back completely free allocator-owned arenas, their metadata included, instead of leaving them for the process lifetime. An arena reserved or managed through the public C API remains pinned for the process lifetime, even if it is non-exclusive or no arena ID was requested. A returned mi_arena_id_t therefore stays valid after reclaim; there is no public API to release the ID or unpin its arena.

An arena is reserved on demand and, without this flag, nothing in the allocator ever gives one back before the process exits – a block that leaves an arena only returns its slices, and the purge that follows merely decommits them. What stays behind is the arena’s whole bookkeeping: the mi_page_t table (2.8 MiB per GiB of arena) and its bitmaps, committed at initialization. That is a function of the process’s PEAK, not of its live set, which is what a long-running service sees as arena metadata that never shrinks (the case this was added for).

Releasing an arena is not a purge-sized operation: its bitmaps and its slot in the sub-process’s arena table are lock-free state that any allocation can reach, so the pass requires proof that no other thread of the sub-process is inside the allocator for its whole duration – every registered thread claimed at once through the same park protocol purge_all_ex already uses (with the owner-gate feature that is every thread outside an allocator call; otherwise the threads parked in park_while_idle). A sub-process where that cannot be established is reported in PurgeAllReport::subprocs_pending with nothing released, and the call is then simply a purge. It may use the wait_ms owner-acquisition budget, but never waits while holding the arena lock.

// From a quiescent point: hand back the arenas the peak left behind.
let (status, report) = mi::purge_all_ex(mi::PurgeFlags::FORCE_RECLAIM, 100);
assert_ne!(status, mi::PurgeStatus::Busy);
if report.reclaimed {
    assert_eq!(report.subprocs_pending, 0);
}

Source