Skip to content

A page grows with headroom, so an append stops copying the page - #629

Merged
matrixarkai merged 1 commit into
mainfrom
perf/page-growth-headroom
Nov 13, 2026
Merged

matrixarkai merged 1 commit into
mainfrom
perf/page-growth-headroom

Conversation

@matrixarkai

Copy link
Copy Markdown
Owner

What was wrong

A page payload asked the allocator for exactly the bytes each append added. Every append could then reallocate the buffer and, once the allocator couldn't extend it in place, copy the whole page. Profiled with callgrind on the journal door at three replicas:

  • 1 KiB puts: realloc was ~13.7% of all instructions, reserve_exact alone 7.2%.
  • 256 KiB puts: realloc was 38% and memmove 35% of the profile.

The change

reserve_page_growth (in chunk_writes.inc.rs, used by both the single and the batch write path) grows the payload with headroom of a sixteenth of its current length. Growth is geometric, so a page reallocates about once per 6.25% it grows instead of once per append, and the spare room is bounded at 6.25% of the page regardless of how many writes built it. A write that grows the page by more than that asks for exactly what it needs, so a page filled by large objects carries no spare room.

Doubling was the alternative, and it is why the exact reserve existed: it left a page holding up to 1.9x what it stores (163 MB of capacity for 87 MB of data at three replicas).

Measured

Callgrind, journal door, three replicas:

workload before after
1,000 puts of 1 KiB, instructions/put 158,343 152,246 (-3.9%)
120 puts of 256 KiB, total instructions 25.32M 22.32M (-11.9%)

The first try used an eighth of headroom: -5.3% and -20.6%, but the published data term read 3.06x. I took the sixteenth because it moves the memory figures about half as far for most of the CPU saving.

The cost: memory, stated up front

A page built by small appends now holds up to 6.25% above the floor. Measured in release:

row total before -> after data term before -> after
64 KiB x 1,000 3.01x -> 3.01x 3.00x -> 3.00x
4 KiB x 4,000 3.08x -> 3.14x 3.00x -> 3.05x
1 KiB x 8,000 3.32x -> 3.34x 3.02x -> 3.02x
striped vs replicated, 1 KiB x 1,000 1.97x / 3.46x -> 2.00x / 3.54x

The metadata line (290 bytes an object plus 164,232 fixed) is unchanged. The README and docs/footprint.md tables, the data-term wording, and the striped comparison are updated from these measurements. Three tests pinned the floor exactly (a_store_holds_one_and_a_half_copies_of_its_payload_when_it_stripes, a_striped_store_is_still_striping_after_a_snapshot_round_trip, the_published_striped_amplification_is_the_one_this_tree_produces); they now assert the floor plus the headroom band, so a regression below the floor still fails.

Tests

  • New a_page_filled_by_small_appends_reallocates_rarely_and_holds_bounded_slack: 900 appends of 1 KiB -> 91 reallocations (the exact reserve took 900) and 11,904 bytes of slack (1.3%). Planted checks: the exact reserve fails it on the reallocation count, and plain doubling fails it on the slack bound.
  • Full lib suite: 682 pass. The one failure, the_published_mutation_copy_figures_are_the_ones_this_tree_produces (README 2485 vs tree 2557), fails identically on unmodified main and is untouched here.

🤖 Generated with Claude Code

A page payload asked the allocator for exactly the bytes each append added. Every append could
then reallocate the buffer and, once the allocator could not extend it in place, copy the whole
page: 7% of a profile of 1 KiB puts and a third of one of 256 KiB puts was that copy.

The payload now grows with headroom of a sixteenth of its length, via reserve_page_growth. Growth
is geometric, so a page reallocates about once per 6.25% it grows instead of once per append,
and the spare room is bounded at 6.25% of the page. A write that grows the page by more than
that asks for exactly what it needs, so a page filled by large objects carries no spare room.
Doubling was the alternative and is why the exact reserve existed: it left a page holding up to
1.9x what it stores.

Measured with callgrind on the journal door at three replicas: 158,343 -> 152,246 instructions
per put at 1 KiB, and 25.32M -> 22.32M total over 120 puts of 256 KiB.

The cost is memory, and it is stated rather than hidden: a page built by small appends now holds
up to 6.25% above the floor. The published data term for 4 KiB objects reads 3.05x instead of
3.00x and its total 3.14x instead of 3.08x; 1 KiB objects read 3.34x instead of 3.32x; the 64 KiB
row is unchanged. The README and docs/footprint.md tables, the striped-versus-replicated
comparison, and the three tests that pinned the floor exactly now assert the floor plus the
headroom band.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@matrixarkai
matrixarkai merged commit eb8fe7d into main Nov 13, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants