Skip to content

docs(cuda): clarify mapped-page eviction - #10882

Merged
0ax1 merged 2 commits into
developfrom
ad/cuda-mapped-page-cache-docs
Nov 4, 2026
Merged

0ax1 merged 2 commits into
developfrom
ad/cuda-mapped-page-cache-docs

Conversation

@0ax1

@0ax1 0ax1 commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Corrects the documentation for release_file_mappings and
vx_cuda_release_file_mappings. Keeping a file mapped does not pin its
pages in memory: memory pressure can still reclaim them.

On Linux, both posix_fadvise(POSIX_FADV_DONTNEED) and
/proc/sys/vm/drop_caches skip pages mapped into a process. Release
Vortex's cached mappings before using either for cold-cache measurements.
Mappings still used by open readers remain mapped until those readers
are released.

Changes

  • Replace the claim that mapped pages cannot be evicted with the
    distinction between explicit cache eviction and memory-pressure reclaim.
  • Document both Linux eviction methods.
  • Include the memory-pressure caveat in both Rust and FFI documentation.
  • Regenerate the C header through cbindgen to match the FFI docs.

Documentation only; no runtime behavior changes. No builds, tests, or
benchmarks were run.

@0ax1 0ax1 added the changelog/docs A docs change label Oct 27, 2026
@0ax1

0ax1 commented Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

@claude review this pr in depth

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @0ax1's task in 56s —— View job


Review: docs(cuda): describe what keeps mapped files in the page cache

The old wording was wrong. Mapped pages aren't pinned, and memory pressure reclaims them like any other clean file page, so fixing it is worthwhile. I found one real accuracy gap in the new wording and two small nits.

1. drop_caches also skips mapped pages, so "with it" is too narrow (should fix)

The new docs, and the PR body ("Only posix_fadvise(DONTNEED) … skips pages mapped into a process"), suggest that fadvise is the only eviction method that needs the mappings released first. That isn't true on Linux. echo 3 > /proc/sys/vm/drop_caches takes the same kernel path:

  • fadvise(DONTNEED) → invalidate_mapping_pages()
  • drop_caches → drop_pagecache_sb() → invalidate_mapping_pages()

From there, mapping_try_invalidate() → mapping_evict_folio() returns early whenever folio_mapped(folio), so mapped pages survive both.

This matters in this repo because the cold-cache tooling here uses drop_caches, not fadvise:

  • bench-orchestrator/bench_orchestrator/cli.py:173
  • scripts/random-access-split.py:32
  • scripts/string-split.py:26
  • scripts/compress-split.py:27

A long-lived host using the FFI might read "evict files with posix_fadvise" and conclude that drop_caches doesn't need vx_cuda_release_file_mappings(). It does, and its cold-cache numbers would quietly come out warm.

Suggested wording for ffi/src/lib.rs (cbindgen regenerates the header from it):

/// Scans keep their files mapped so later scans of the same file reuse filled page tables.
/// Linux skips pages mapped into a process when it drops the page cache on request, through
/// `posix_fadvise(POSIX_FADV_DONTNEED)` or `/proc/sys/vm/drop_caches`, so call this before
/// evicting files, for example before a cold-cache measurement. Mappings still used by open
/// streams stay mapped until those streams are released.

Use the same idea in pooled_read_at/file.rs:248-251, keeping its "although memory pressure can still reclaim them" clause. The PR description should change the same way.

Fix this →

2. Say this is Linux behaviour (nit)

posix_fadvise advice is only a hint under POSIX. "Skips mapped pages" is Linux behaviour (macOS has no posix_fadvise), and the crate is Linux-centric anyway. Starting the sentence with "Linux" (or "On Linux") stops it reading like a portable guarantee. The suggestion above already does this.

3. The two doc comments disagree (nit)

The Rust doc in file.rs says memory pressure can still reclaim mapped pages, but the FFI doc and header leave that out. Embedders reading vortex_cuda.h are the ones most likely to wonder whether keeping mappings costs memory, so the clause probably belongs there too. Otherwise the two can stay as they are.

Things I checked that are fine

  • Page-level accuracy: "Pages mapped into a process" is the right granularity. The kernel checks whether the folio is mapped in a page table, not whether the file has an mmap. uncached_ranges_take_the_staged_path (file/tests.rs:556) relies on this: it runs fadvise on a file that is mmapped but not yet faulted in and expects the pages to be evicted. The new wording agrees with that test, and the old wording ("a mapped page cannot be dropped") didn't.
  • Header vs. Rust source: vortex_cuda.h is generated by cbindgen in ffi/build.rs, and the header text matches the new lib.rs doc comment word for word. CI's git status --porcelain check should pass.
  • Line width: All doc lines stay within the existing ~100-column width.
  • Spelling: No typos-checker concerns.

Verdict

Good to merge once the drop_caches gap (item 1) is fixed. Items 2 and 3 are optional.

I only read the code (diff, kernel call paths, the in-repo cold-cache scripts and related tests). I didn't run builds or tests because the change is documentation only.

@codspeed

codspeed Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

1 warning

⚠️ Walltime results may be unreliable

Some benchmarks used the Walltime instrument outside CodSpeed Macro Runners, which can make the results inconsistent.

Learn more about Macro Runners

See affected benchmarks

✅ 1765 untouched benchmarks
⏩ 130 skipped benchmarks1
🗄️ 47 archived benchmarks run2


Comparing ad/cuda-mapped-page-cache-docs (f81c155) with develop (0151998)

Open in CodSpeed

Footnotes

  1. 130 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

  2. 47 benchmarks were run, but are now archived. If they were deleted in another branch, consider rebasing to remove them from the report. Instead if they were added back, click here to restore them. ↩

0ax1 added 2 commits November 4, 2026 12:28
`release_file_mappings` and `vx_cuda_release_file_mappings` said mapped
pages cannot be dropped from the page cache. Mapped pages are not
locked: memory pressure reclaims them as usual. Only
`posix_fadvise(DONTNEED)`, which cold-cache measurements use to evict
files, skips pages mapped into a process, which is why the mappings
must be released first. Say so.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
@0ax1
0ax1 force-pushed the ad/cuda-mapped-page-cache-docs branch from e4c993d to f81c155 Compare November 4, 2026 12:31
@0ax1
0ax1 marked this pull request as ready for review November 4, 2026 12:33
@0ax1
0ax1 requested review from mprammer and robert3005 November 4, 2026 12:33
@0ax1 0ax1 changed the title docs(cuda): describe what keeps mapped files in the page cache docs(cuda): clarify mapped-page eviction Nov 4, 2026
@0ax1
0ax1 merged commit a52afdb into develop Nov 4, 2026
147 of 148 checks passed
@0ax1
0ax1 deleted the ad/cuda-mapped-page-cache-docs branch November 4, 2026 13:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog/docs A docs change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants