Place the closed-trade read cache by row count - #797

Summary

A script that reads its closed trades again and again (strategy.closedtrades accessors in a loop) is about 1.9 to 2.0 times slower on main than on 1.10.0 on histories of 15,500 and 39,456 closed trades (the 1.10.0 cache holds 65,536 rows; main is faster than 1.10.0 on such scans at 75,000 closed trades and above). This change restores the 1.10.0 speed of that script (1.03 of the 1.10.0 engine time on a 15,500-trade history) and lets the closed-trade read cache commit up to four times fewer pages while the history is small. Every value a script reads is unchanged.

PR type: code (engine source, tests and documentation).

What changes

• Placement by row count. While the ledger holds at most as many rows as the read cache has entries (215,070 by default), row n owns slot n: one way, one probe per lookup, and only the pages that the rows reach are committed. With more rows the four-way sets apply as before. An append that takes the ledger past the cache's rows, and a rewind that brings it back to them, drop every cached row and keep the allocated pages.
• Least-recently-used hit rule. In a four-way set a hit on the most recent entry changes nothing, and a hit on any other entry ages only the entries more recent than it, so a full set replaces the entry touched longest ago, as docs/pages/memory-management.md says. Before, every hit rewrote the rank of every other entry of the set.
• A miss is probed once. The numeric and text accessors test the cache first and then call the miss path, which no longer probes the set a second time.
• src/engine_orders.cpp is the only source file that changes; the header changes comment lines only. No layout, ABI or public interface changes.

Memory

Below the cache's rows the cache commits only the pages the rows reach: 25,000 closed trades hold 98 pages (7.8 MB) where four-way sets held 391 pages (31.2 MB), up to four times less. At and above the cache's rows the pages are the same as before. The declared cap and the cache's row count do not change; the ledger's fixed base grows by 8 bytes (one flag in its private state), so resident_cache_bytes() and the accounted charge are 8 bytes larger in every run (22,624 to 22,632 bytes for an empty ledger on the aarch64 build host).

Measurements

Every timing figure in this description comes from one build per arm. The rounds repeat those binaries; they are not independent build replicates. Each cell is the engine time divided by the engine time of 1.10.0 built with the same compiler (GCC 13.3) in the same round, so 1.0 is equal and 2.0 is twice as slow. aarch64 build host, one pinned core, arms rotated within each round, cold start; median and range over the rounds. Timings on x86-64 were not measured.

Against the released 1.10.0 binary (built with GCC 11.4) the same first script takes 1.066 [1.018 - 1.082] with this change and 2.017 [1.910 - 2.065] on main; the local 1.10.0 build is 1.038 [1.001 - 1.051] of that binary, which is the compiler difference. The reports of the first script are identical field by field (15,500 trades, 31,000 equity points) on main and on this change; the 1.10.0 report was not compared field by field here.

The last row is the one place where this change is slower than main: with 250,000 closed trades, above the cache's rows, scanning all of them takes 40.1 s against 27.3 s on main (1.48 times) and 137.7 s on 1.10.0. In that row both 1.10.0 rounds and one round of this change ran with other tasks using more than 10 percent of the pinned core (12.8 and 18.3 percent for 1.10.0, 12.2 percent for this change), and only two rounds were run.

The difference comes from the replacement rule of the four-way regime. Main's hit rule aged every other entry of a set on every hit, which is not the documented rule, and a script that calls several accessors on the same row hits the entry it has just loaded several times in a row; a cyclic scan over a history larger than the cache's rows then keeps part of its rows by accident. With the documented least-recently-used rule it keeps none. The cache counters of a unit test show it: a cache of 1,024 entries and a cyclic scan over 4,096 rows with six accessor calls on each row, 512 of the 4,096 first accesses hit on main and none on this change; with one accessor call per row the counts are identical.

Tests

• The placement oracle tests/ledger_default_cache_rows.hpp takes the number of rows the ledger holds and models both placements from the documented geometry (no product code is called). Nine tests that compared resident bytes or entry counts with it state both placements and keep exact equality: test_trade_ledger_cache_policy, test_p2cx_tledger_budget, test_p2cx_tledger_io, test_closed_trade_text_reads, test_ledger_retired_cache_bound, test_ledger_cache_bound, test_trade_ledger_cache_sweep, test_report_sink_trade_residency, test_selected_metrics_l17b. test_report_sink_trade_residency now samples 100,000, 250,000 and 1,000,000 trades: the heap plateau claim holds only past the cache's rows (215,070), and every sample's cache pages are checked exactly. In test_selected_metrics_l17b, only the upper side of the peak allowance between the 70,000-row and the 100,000-row sink runs adds 9,345,024 bytes for cache-page growth; one 64 KiB scratch window remains on both sides. In the focused Release build the larger run's peak exceeds the smaller run's by exactly 9,345,024 bytes in all three modes. In Debug and sanitizer builds the allocation counter does not see the cache pages and the two peaks are equal, so the upper allowance is loose by that growth in those profiles. Release retains one scratch window of slack around its observed page growth.
• Three new tests: test_ledger_lru_victim (the replacement order), test_ledger_probe_once (a miss is probed and counted once) and test_ledger_adaptive_cache (one probe per lookup below the cache's rows, the change of placement drops rows and keeps pages, a rewind returns to the first placement, a copy keeps values).
• On an aarch64 build host: the 18 closed-trade cache tests, 15 further tests that observe the cache and the 3 new tests (36 in all) pass. The nine changed tests fail on main when run with this change's expectations, and the old expectations fail on this change: the expectations tell the two placements apart. A trace of every value read across appends below, at and past the cache's rows, replaced rows, a rewind and a copy is identical on main and on this change.
• Mutation check of the new expectations (aarch64 build host): nine deliberately wrong variants, seven of the engine change (the change of placement one row early or one row late, no drop of the cached rows at the change, no change on an append, no change on a rewind, pages released at the change, two ways in the first placement) and two of the oracle (the boundary at exactly the cache's rows, an unclipped last page), are each rejected by at least one of the tests.

🤖 Generated with Claude Code