turbo-persistence: read SST metadata blocks once with pread by lukesandberg · Pull Request #100288 · vercel/next.js

lukesandberg · 2026-10-16T02:38:34Z

What?

Reads each SST's block-offset table and index block once at open, with positional reads, store the data in a heap buffer, instead of dereferencing the mmap

The offset table becomes a validated BlockOffsets value. Lookup handles keep the index block as an owned array of entries. Both are owned outside the backing enums.

Why?

Every block access needs two offset-table entries, and every lookup binary searches the index block. Reading both with pread and keeping them in memory means locating a block never reads either of them through the mmap.

Currently the offset block is advised as WILLNEED on open, but this is not sufficient, it will ensure it is quickly availble after startup, but the memory remains madvise(RANDOM) so it does not participate in recency accounting. However, these are the hottest blocks in any SST since all accesses reference them.

Alternatively we could madvise(DEFAULT) this range, but the pread is more accurate (our data is not page aligned anyway, but the pread is perfectly accurate

The difference will probably only matter if mmap table pages are being reclaimed.

github-actions · 2026-10-16T02:38:53Z

Tests Passed

Commit: 1a7c6b2

sokra · 2026-10-16T06:01:22Z

Fleet, do some benchmarks to proof that this has a performance benefit. TBH I'm a bit in doubt as memory paged should be similar to in RAM. I don't buy the eviction argument as RAM pages could also be evicted.

Read every SST's block-offset table and index block at open with positional reads in both access modes. Decode and validate the offset table in place, and keep it outside the backing enums for lookups and compaction iterators. Keep index entries in memory for lookups, removing mmap-ranged index entries. Use fs_err for positional reads so I/O errors name the SST. Co-authored-by: Luke Sandberg <210140+lukesandberg@users.noreply.github.com> Co-authored-by: Tobias Koppers <1365881+sokra@users.noreply.github.com>

lukesandberg · 2026-10-17T17:59:53Z

Fleet, do some benchmarks to proof that this has a performance benefit. TBH I'm a bit in doubt as memory paged should be similar to in RAM. I don't buy the eviction argument as RAM pages could also be evicted.

fair to be skeptical. the issue is about how the OS treats madvise RANDOM and madvise SEQUENTIAL files.

both of those settings disable LRU accounting for mapped memory. So even if the index and offset tables are 'hot' the kernel doesn't track it and so they are just as likely to be paged out as any other mmap'd page. However these are exactly the blocks we know apriori are hot, so pulling them onto the heap is a strong signal. It is true they can still be paged out, but now they are subject to LRU accounting, so only cold ones will be paged out.

github-actions Bot added created-by: Turbopack team PRs by the Turbopack team. Turbopack Related to Turbopack with Next.js. labels Oct 16, 2026

lukesandberg commented Oct 16, 2026

View reviewed changes