Skip to main content

recommit

Function recommit 

Source
pub unsafe fn recommit(base: *mut u8, start: usize, end: usize) -> bool
Expand description

Recommit pages [base + start, base + end) previously passed to decommit. On Windows this re-commits physical pages (VirtualAlloc(MEM_COMMIT)); on Unix re-access is implicit so this is a no-op. On the Darwin family (macOS/iOS/tvOS/watchOS) specifically, whether re-access reads back zeroed pages or the pre-decommit contents is not guaranteed either way — see decommit’s Darwin caveat for why.

Returns true if the range is now committed (or the call was a well-formed no-op — an empty PAGE-ALIGNED range, start == end), and false if the OS refused to commit the pages (commit-charge exhaustion / true OOM) OR the offsets violated the contract below. On false the caller MUST NOT write into [base+start, base+end). Never panics. For the cause use try_recommit.

§Safety

  • base must be the as_ptr of a live reservation whose [base+start, base+end) range was previously decommitted.
  • end <= reservation.len() (the reservation’s usable span, in bytes) — this is a MANDATORY precondition of the pointer arithmetic this function performs internally (base.add(start) in the Windows backend’s recommit_pages_impl; the Unix and miri backends are no-ops but the contract is stated platform-independently), not merely a functional/behavioral preference. Before task #1229/F6 this function was the only range-taking free function whose # Safety lacked the bound: decommit’s states it in full (task #1213/L2, whose wording this matches), try_decommit and decommit_lazy carry it (restated in prose / in full — the latter since task #1235, which replaced decommit_lazy’s earlier bare same-contract reference), and the commit_range pair spells it out as end <= len. For an unsafe fn, a bounds requirement that determines whether pointer arithmetic is even defined belongs inside # Safety itself, restated in full. Passing end > reservation.len() is undefined behavior (with start <= end the bound is what keeps the backend’s base.add(start) offset in-bounds and the OS call’s span [base+start, base+end) inside the reservation), distinct from — and a strictly worse violation than — the page_size()-multiple contract below, which merely returns false on violation, never UB. Callers through the safe Reservation::recommit / Reservation::try_recommit methods are not exposed: both bounds-check end <= self.len() before delegating here, so the gap reaches only callers of this free function directly.
  • start/end must be multiples of the runtime page size (page_size()) with start <= end — a violation returns false (task #712: an earlier version of this function clamped a contract violation to the WRITE-PERMITTING true sentinel, which already caused a real crash — see https://github.com/PHPCraftdream/sefer-alloc/blob/main/docs/CORRECTNESS_OPEN_ITEMS.md item 6 for the incident this class of bug produces on Windows).