Repository navigation
Commit b4a2c19
authored
engine: let the command scratch cache size be raised past 64 KiB (#661)
Make the command-scratch cache size buildable at any size.
**Problem**
Changing `kCacheBytes` above its default did not compile: the per-backing slot table was an inline array sized from `kCacheBytes`, and `static_assert(sizeof(CachedScratchBacking) <= 2 * 1024)` failed (`command_scratch_cache.hpp:76`).
**Change**
- The slot table moves out of the object into one construction-time `new (std::nothrow)` allocation of `slot_count_` entries (the slots this backing actually uses), beside the page buffer. A failed allocation reports the same typed out-of-memory failure as the page buffer.
- The `static_assert` now covers only the fixed part of the object (1 KiB). There is no upper cap on the cache size; sizes are `std::size_t` and page ids are 64-bit.
- The memory constant still charges the worst case (`kMaxSlots` entries at 512-byte pages): 202,752 bytes at the default, unchanged.
- Docs state the formula; the source-bounds inventory records the new allocation site.
### Large cache sizes
The cache size is a plain `std::size_t` constant (64 KiB by default) and nothing in the class caps it: page ids are 64-bit, the slot table is sized from the constant and the page size, and the only `static_assert` covers the fixed part of the object.
What was run, on Linux CI machines in a Release build, with only the one line that sets the constant changed:
- Before this change, on main, raising the constant to 1 MiB does not build: the `static_assert` on the object size fails inside the library itself.
- With the constant raised to 1 GiB and to 4 GiB the library and every test target build, and seven tests were run once each (results below). An earlier head of this change, built at 1 MiB, 16 MiB, 64 MiB and 256 MiB, compiled the library; its only compile errors were two default-size assertions in the new test, since made size-independent.
- At 1 GiB and at 4 GiB, one run each of seven tests (the new slot-table test, the two allocation-failure tests, the summary-metrics allocation test, the command-store spill test, the report-sink curve test and the production file-backing test):
- Pass at both sizes: the new slot-table test (19 s at 1 GiB, 88 s at 4 GiB), both allocation-failure tests, the summary-metrics allocation test and the spill test (28 s and 88 s). These are the product rows: they build a real cache, count its allocations and compare every read, hit and miss with an independent model.
- Two tests do not pass at either size; both are limits of the test, not of the cache:
- the report-sink curve test fails only above the default cache size: it asserts that the largest array of its run is the report curve, which holds only while the cache buffer is smaller than the curve (true at the 64 KiB default, where the test passes; the same assertion failed at 1 MiB to 256 MiB before the last edit of this change);
- the production file-backing test fails identically on unchanged main on the same box: it needs real file media, and the scratch filesystem of these runs is an overlay that cannot provide it (see the control run).
- At the default size, the full verification of this exact head (all eight steps) is the merge evidence; its result is posted on this pull request.
Memory at a large constant: the slot table is allocated with the slot count of the page size of each store, so with 64 KiB pages and a 4 GiB constant it is 64 Ki entries, not the 8 Mi entries of the worst case (512-byte pages). The documented fixed bound still charges the worst case, 3 * (cache bytes + table at 512-byte pages + fixed object), which is 202,752 bytes at the default.
This replaces #658: the same change rebuilt as one commit on the current main, so that its message names the documentation sentences it replaces.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
Commits on the PR head (verbatim):
* 3188351 engine: let the command scratch cache size be raised past 64 KiB
The command-store cache decorator kept its direct-mapped slot table inline
(`std::array<ScratchPageId, kCacheBytes / 512>`), so the object grew with the
cache constant and the size assertion failed at every cache size above
64 KiB (16,488 bytes at 1 MiB, about 4.2 MB at 256 MiB). The cache size could
therefore not be raised and built.
The table now lives in one allocation made at construction beside the page
buffer, with the same typed out-of-memory failure, and the assertion states the
fixed part of the object only. The table has one entry per slot of the store's
own page size (`kCacheBytes / page size` entries), so a store with 64 KiB pages
and a 4 GiB constant holds 64 Ki entries, not the 8 Mi entries of the worst
case of 512-byte pages. The documented fixed bound still charges that worst
case, as a formula of the constants: `3 * (kCacheBytes + kMaxSlots *
sizeof(ScratchPageId) + kFixedObjectBytes)`, which is 202,752 bytes (198 KiB)
at the default of 64 KiB. The slot function, admission rule, resident prefix,
hit and miss behaviour and the bytes are unchanged; nothing in an I/O operation
allocates or throws. The class lives in a source-only header, so no public
header or ABI declaration changes. There is no upper cap on the constant: page
ids and sizes are 64-bit, and the only limit is memory, reported as the typed
out-of-memory failure.
Tests: a new test drives a real decorator against an independent direct-mapped
model at 512 B, 4 KiB, 64 KiB and 64 KiB + 1 pages (the last must bypass the
cache) and asserts the bound formula at the default. The two existing
allocation-census tests now count the slot table: the run-scratch allocation
test derives the expected table size from each entry's page size (the exit
entry opens its store with the platform page size), and the report-sink curve
test counts the table in its array census. The source allocation-bound
inventory lists the new site.
Large cache sizes. With only the line that sets the constant changed, on Linux
CI machines in a Release build: before this change, on main, a constant of 1 MiB
does not build (the size assertion fails inside the library itself). With the
constant raised to 1 GiB and to 4 GiB the library and every test target build,
and seven tests were run once each (results below). An earlier head of this
change, built at 1 MiB, 16 MiB, 64 MiB and 256 MiB, compiled the library; its
only compile errors were two default-size assertions in the new test, since
made size-independent. At 1 GiB and at 4 GiB, seven tests were
run once each; the new slot-table test, both allocation-failure tests, the
summary-metrics allocation test and the spill test pass at both sizes. Two do
not, and both are limits of the test, not of the cache:
- the report-sink curve test fails only above the default cache size: it asserts
that the largest array of its run is the report curve, which holds only while
the cache buffer is smaller than the curve;
- the production file-backing test fails identically on unchanged main on the
same box: it needs real file media, and the scratch filesystem of these runs
is an overlay that cannot provide it.
Replaced documentation sentences, named for the documentation revert check.
This change replaces three sentences that state the fixed bound as a bare
figure, all introduced by commit 8713a82 ("scratch: keep a run's command
scratch resident up to a fixed size; sync the report sink on"). Each is
replaced by the same bound written as a formula of the cache constants, which
is still 202,752 bytes at the default:
- docs/design/arena-bound.md: "The command-scratch resident/cache ledger term
is fixed **K = 202,752 bytes/run**:"
- docs/design/arena-bound.md: "`3 * (65536 + 2048)`, named at
`src/command_scratch_cache.hpp:N`, including three 64-KiB buffers and their
decorator/slot-key objects (`static_assert(`"
- docs/pages/memory-management.md: "Fixed K = 202,752 B (198 KiB) per run:
three 64 KiB page buffers plus 2 KiB per decorator, including slot keys
(`CachedScratchBacking::kCommandScratch"
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>1 parent 18f55bb commit b4a2c19
10 files changed
Lines changed: 463 additions & 45 deletions
File tree
- ci
- docs
- design
- pages
- src
- tests
- cr150.d
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1354 | 1354 | | |
1355 | 1355 | | |
1356 | 1356 | | |
1357 | | - | |
| 1357 | + | |
1358 | 1358 | | |
1359 | 1359 | | |
1360 | 1360 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
13174 | 13174 | | |
13175 | 13175 | | |
13176 | 13176 | | |
| 13177 | + | |
| 13178 | + | |
| 13179 | + | |
| 13180 | + | |
| 13181 | + | |
| 13182 | + | |
| 13183 | + | |
| 13184 | + | |
| 13185 | + | |
| 13186 | + | |
| 13187 | + | |
| 13188 | + | |
13177 | 13189 | | |
13178 | 13190 | | |
13179 | 13191 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
692 | 692 | | |
693 | 693 | | |
694 | 694 | | |
695 | | - | |
696 | | - | |
697 | | - | |
| 695 | + | |
| 696 | + | |
| 697 | + | |
698 | 698 | | |
699 | | - | |
| 699 | + | |
700 | 700 | | |
701 | 701 | | |
702 | 702 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
321 | 321 | | |
322 | 322 | | |
323 | 323 | | |
324 | | - | |
| 324 | + | |
325 | 325 | | |
326 | 326 | | |
327 | 327 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
36 | 36 | | |
37 | 37 | | |
38 | 38 | | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
39 | 43 | | |
40 | | - | |
41 | 44 | | |
42 | 45 | | |
43 | 46 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | | - | |
17 | | - | |
18 | | - | |
19 | | - | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
20 | 20 | | |
21 | 21 | | |
22 | 22 | | |
23 | | - | |
| 23 | + | |
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
27 | | - | |
28 | | - | |
29 | | - | |
30 | | - | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
| |||
56 | 56 | | |
57 | 57 | | |
58 | 58 | | |
59 | | - | |
60 | | - | |
| 59 | + | |
| 60 | + | |
61 | 61 | | |
62 | 62 | | |
63 | 63 | | |
| |||
70 | 70 | | |
71 | 71 | | |
72 | 72 | | |
73 | | - | |
| 73 | + | |
74 | 74 | | |
75 | 75 | | |
76 | | - | |
77 | | - | |
| 76 | + | |
| 77 | + | |
78 | 78 | | |
79 | 79 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
0 commit comments