Skip to content

Commit 6548775

Browse files
luisleo526claude
andcommitted
TradeLedger: budgeted decoded-row read cache, equal strings reused on replace (candidate)
A script that reads strategy.closedtrades every bar decoded each historical row per field call: an index pread below the 64-row descriptor window and four string preads outside the 10752-byte payload tail. Add a separate read cache of decoded closed rows, direct-mapped by global index, one integer budget (ledger_rows, default 4096, max 65536; entry = 168-byte record + key + generation + 1024 inline string bytes, kLedgerEntryBytes), with resident_cache_bytes(rows) for the memory formula, a setter that is frozen after the first append, and invalidation on replace, resize (rewind), seal, move and clear. Rows whose four strings exceed the allowance are not cached and keep the scratch path. replace() reuses an unchanged string extent instead of appending the same bytes again. kResidentRows (64), kRecordBytes, resident_size() and resident_base() are unchanged. Tests: test_p2cx_tledger_io (syscall counter, zero reads/writes per bar at the default budget, oracle-compared), test_p2cx_tledger_budget (budget formula, typed refusal, stale-value and lifecycle checks). Refusal currently uses setting_rejected; to be aligned with the shared resident-budget code. Edit-only lane: nothing built or run at commit time; lab verification follows. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent c82fd00 commit 6548775

6 files changed

Lines changed: 781 additions & 10 deletions

File tree

‎include/pineforge/trade_ledger.hpp‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ inline namespace engine_script_run_v19 {
1818
// A kResidentRows descriptor window and an equally sized fixed byte tail of
1919
// the string payload stay in memory. All four string payloads and all older
2020
// mutable/sealed descriptors use the existing run-owned positional scratch
21-
// files. Owning Trade values belong to readers, so no arbitrary-width string
22-
// is hidden in the resident window.
21+
// files. A separate, budgeted read cache retains numeric records and up to
22+
// kCacheStringBytes of decoded string bytes per row. Wider rows use scratch.
23+
// Owning Trade values still belong to readers.
2324
//
2425
// Reads own their values. No reference or contiguous pointer into an
2526
// evictable page escapes. Iteration visits [base(),size()) as before, now
@@ -33,6 +34,15 @@ class TradeLedger {
3334
// storage type is complete.
3435
static constexpr size_type kRecordBytes = 168;
3536
static constexpr size_type kResidentRows = 64;
37+
// One knob for this cache kind: ledger_rows. Each entry contains a
38+
// 168-byte numeric/extent record, a global key and validity generation,
39+
// and exactly 1,024 inline string bytes (all four strings combined).
40+
// No per-entry heap allocation or growing offset/string directory.
41+
static constexpr size_type kCacheStringBytes = 1024;
42+
static constexpr size_type kLedgerEntryBytes =
43+
kRecordBytes + 2 * sizeof(size_type) + kCacheStringBytes;
44+
static constexpr size_type kDefaultCacheRows = 4096;
45+
static constexpr size_type kMaxCacheRows = 65536;
3646
using Visitor = std::function<bool(size_type, const Trade&)>;
3747

3848
class const_iterator {
@@ -69,6 +79,22 @@ class TradeLedger {
6979
// Bind before the first spill. No mapping or in-memory offset directory.
7080
void set_scratch_directory(const std::string&);
7181
const std::string& scratch_directory() const;
82+
// Configure before the first append/spill; clear() preserves the budget.
83+
// Valid rows: [1,65536]; invalid/late settings throw a coded
84+
// std::invalid_argument (setting_rejected, reason value_below_minimum,
85+
// value_above_maximum or frozen). Default: 4,096 rows, 4,947,968 entry
86+
// bytes on 64-bit targets; maximum: 65,536 rows, 79,167,488 entry bytes.
87+
void set_cache_rows(size_type rows);
88+
size_type cache_rows() const;
89+
// Accounted ledger/cache storage: rows*kLedgerEntryBytes + a fixed base
90+
// (sizeof ledger + State). Excludes allocator overhead, scratch/OS pages,
91+
// configured directory strings, returned owning Trades and the explicit
92+
// legacy materialize() map. Validates the same row range as the setter.
93+
static size_type resident_cache_bytes(size_type rows);
94+
size_type cache_resident_bytes() const;
95+
// Occupied decoded entries only; separate from resident_size()'s legacy
96+
// descriptor/materialization accounting.
97+
size_type cache_size() const;
7298
void clear();
7399
void reserve(size_type);
74100
size_type size() const;
@@ -81,6 +107,9 @@ class TradeLedger {
81107

82108
// read() spans the whole exact source; at()/[] retain the checked
83109
// unsealed-window contract for existing settlement callers.
110+
// Hits allocate only the owning strings already required by read().
111+
// Direct-mapped eviction above cache_rows(), or an oversized string set,
112+
// retains the existing scratch path; a history loop can still cost O(T).
84113
Trade read(size_type global) const;
85114
Trade operator[](size_type global) const;
86115
Trade at(size_type global) const;

‎src/engine_orders.cpp‎

Lines changed: 139 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -375,11 +375,75 @@ struct TradeLedger::State {
375375
std::array<char, kPayloadTailBytes> payload_tail{};
376376
std::string directory;
377377
mutable std::map<size_type, Trade> materialized;
378+
// Packed owning string bytes, rather than std::strings whose capacities
379+
// could exceed the advertised bound. Record retains exact numeric bits
380+
// and four string lengths; offsets remain scratch-only metadata.
381+
struct CacheEntry {
382+
Record record{};
383+
size_type global = 0, generation = 0;
384+
std::array<char, kCacheStringBytes> strings{};
385+
};
386+
static_assert(sizeof(CacheEntry) == kLedgerEntryBytes);
387+
size_type cache_rows = kDefaultCacheRows;
388+
mutable std::unique_ptr<CacheEntry[]> cache;
389+
mutable size_type cache_count = 0;
390+
size_type cache_generation = 1;
378391

379392
State() {
380393
index.bound_cache();
381394
payload.bound_cache();
382395
}
396+
static void validate_cache_rows(size_type rows) {
397+
if (rows == 0 || rows > kMaxCacheRows)
398+
throw coded<std::invalid_argument>(RunFailureCode::setting_rejected,
399+
{{"input", "resident.ledger_rows"},
400+
{"reason", rows == 0 ? "value_below_minimum"
401+
: "value_above_maximum"}},
402+
"trade ledger: cache rows outside [1,65536]");
403+
}
404+
const CacheEntry* cached(size_type global) const {
405+
if (!cache) return nullptr;
406+
const auto& entry = cache[global % cache_rows];
407+
return entry.generation == cache_generation && entry.global == global ? &entry : nullptr;
408+
}
409+
void invalidate(size_type global) {
410+
if (cached(global)) {
411+
cache[global % cache_rows].generation = 0;
412+
--cache_count;
413+
}
414+
}
415+
void invalidate_cache() {
416+
cache_count = 0;
417+
// Generations make publication/rewind/move invalidation O(1).
418+
// Even the wraparound fallback touches at most the configured budget.
419+
if (cache_generation == std::numeric_limits<size_type>::max()) {
420+
if (cache)
421+
for (size_type i = 0; i < cache_rows; ++i) cache[i].generation = 0;
422+
cache_generation = 1;
423+
} else {
424+
++cache_generation;
425+
}
426+
}
427+
void remember(size_type global, const Record& record, const Trade& row) const {
428+
const std::array<const std::string*, 4> texts{{
429+
&row.entry_id, &row.entry_comment, &row.exit_comment, &row.exit_id}};
430+
size_type bytes = 0;
431+
for (const auto* text : texts) {
432+
if (text->size() > kCacheStringBytes - bytes) return;
433+
bytes += text->size();
434+
}
435+
if (!cache) cache = std::make_unique<CacheEntry[]>(cache_rows);
436+
auto& entry = cache[global % cache_rows];
437+
if (entry.generation != cache_generation) ++cache_count;
438+
entry.record = record;
439+
entry.global = global;
440+
size_type offset = 0;
441+
for (const auto* text : texts) {
442+
std::copy_n(text->data(), text->size(), entry.strings.data() + offset);
443+
offset += text->size();
444+
}
445+
entry.generation = cache_generation;
446+
}
383447
static std::uint64_t record_offset(size_type global) {
384448
if (global > std::numeric_limits<std::uint64_t>::max() / sizeof(Record))
385449
throw detail::ScratchIoError(EFBIG, "trade ledger offset");
@@ -435,18 +499,28 @@ struct TradeLedger::State {
435499
}
436500
return result;
437501
}
438-
Record store(size_type global, const Trade& row) {
502+
StringExtent reuse_string(const std::string& text, StringExtent old) {
503+
if (text.size() == old.length && text == get_string(old)) return old;
504+
return put_string(text);
505+
}
506+
Record store(size_type global, const Trade& row, const Record* previous = nullptr) {
439507
index.open("pineforge-trade-index");
440508
payload.open("pineforge-trade-payload");
441509
Record record{};
442510
record.entry_time = row.entry_time; record.exit_time = row.exit_time;
443511
record.entry_price = row.entry_price; record.exit_price = row.exit_price;
444512
record.qty = row.qty; record.pnl = row.pnl; record.pnl_pct = row.pnl_pct;
445513
record.entry_bar_index = row.entry_bar_index; record.exit_bar_index = row.exit_bar_index;
446-
record.entry_id = put_string(row.entry_id);
447-
record.entry_comment = put_string(row.entry_comment);
448-
record.exit_comment = put_string(row.exit_comment);
449-
record.exit_id = put_string(row.exit_id);
514+
// Replacements retain equal extents, including embedded NULs. Payload
515+
// growth follows actual string changes, not numeric-update/bar count.
516+
record.entry_id = previous ? reuse_string(row.entry_id, previous->entry_id)
517+
: put_string(row.entry_id);
518+
record.entry_comment = previous ? reuse_string(row.entry_comment, previous->entry_comment)
519+
: put_string(row.entry_comment);
520+
record.exit_comment = previous ? reuse_string(row.exit_comment, previous->exit_comment)
521+
: put_string(row.exit_comment);
522+
record.exit_id = previous ? reuse_string(row.exit_id, previous->exit_id)
523+
: put_string(row.exit_id);
450524
record.max_runup = row.max_runup; record.max_drawdown = row.max_drawdown;
451525
record.commission = row.commission; record.entry_incarnation = row.entry_incarnation;
452526
record.close_cause = row.close_cause; record.is_long = row.is_long;
@@ -474,7 +548,23 @@ struct TradeLedger::State {
474548
row.exit_id = get_string(record.exit_id);
475549
return row;
476550
}
551+
static Trade decode_cached(const CacheEntry& entry) {
552+
Trade row = decode_numeric(entry.record);
553+
const std::array<std::string*, 4> texts{{
554+
&row.entry_id, &row.entry_comment, &row.exit_comment, &row.exit_id}};
555+
const std::array<std::uint64_t, 4> lengths{{
556+
entry.record.entry_id.length, entry.record.entry_comment.length,
557+
entry.record.exit_comment.length, entry.record.exit_id.length}};
558+
size_type offset = 0;
559+
for (size_type i = 0; i < texts.size(); ++i) {
560+
const auto length = static_cast<size_type>(lengths[i]);
561+
texts[i]->assign(entry.strings.data() + offset, length);
562+
offset += length;
563+
}
564+
return row;
565+
}
477566
Record descriptor(size_type global) const {
567+
if (const auto* entry = cached(global)) return entry->record;
478568
if (global >= resident_first) return rows[slot(global)];
479569
Record record{};
480570
index.read(record_offset(global), &record, sizeof(record));
@@ -493,8 +583,15 @@ TradeLedger::~TradeLedger() = default;
493583

494584
TradeLedger::TradeLedger(const TradeLedger& other)
495585
: TradeLedger() {
586+
set_cache_rows(other.cache_rows());
496587
set_scratch_directory(other.state_->directory);
497-
for (size_type i = 0; i < other.size(); ++i) push_back(other.read(i));
588+
// Do not populate/copy the read cache just to clone scratch. Existing
589+
// source hits may serve the copy; misses keep the original O(T) I/O path.
590+
for (size_type i = 0; i < other.size(); ++i) {
591+
const auto* entry = other.state_->cached(i);
592+
push_back(entry ? State::decode_cached(*entry)
593+
: other.state_->decode(other.state_->descriptor(i)));
594+
}
498595
seal(other.base());
499596
}
500597

@@ -508,6 +605,7 @@ TradeLedger& TradeLedger::operator=(const TradeLedger& other) {
508605

509606
TradeLedger::TradeLedger(TradeLedger&& other) : TradeLedger() {
510607
state_.swap(other.state_);
608+
state_->invalidate_cache();
511609
}
512610

513611
TradeLedger& TradeLedger::operator=(TradeLedger&& other) {
@@ -520,6 +618,7 @@ TradeLedger& TradeLedger::operator=(TradeLedger&& other) {
520618

521619
void TradeLedger::clear() {
522620
auto next = std::make_unique<State>();
621+
next->cache_rows = state_->cache_rows;
523622
next->directory = state_->directory;
524623
next->index.set_directory(next->directory);
525624
next->payload.set_directory(next->directory);
@@ -533,6 +632,27 @@ void TradeLedger::set_scratch_directory(const std::string& directory) {
533632
}
534633
const std::string& TradeLedger::scratch_directory() const { return state_->directory; }
535634

635+
void TradeLedger::set_cache_rows(size_type rows) {
636+
State::validate_cache_rows(rows);
637+
if (state_->end != 0 || state_->index.opened() || state_->payload.opened())
638+
throw coded<std::invalid_argument>(RunFailureCode::setting_rejected,
639+
{{"input", "resident.ledger_rows"}, {"reason", "frozen"}},
640+
"trade ledger: cache rows changed after spill");
641+
state_->cache.reset();
642+
state_->cache_count = 0;
643+
state_->cache_rows = rows;
644+
}
645+
TradeLedger::size_type TradeLedger::cache_rows() const { return state_->cache_rows; }
646+
TradeLedger::size_type TradeLedger::resident_cache_bytes(size_type rows) {
647+
State::validate_cache_rows(rows);
648+
return sizeof(TradeLedger) + sizeof(State) + rows * kLedgerEntryBytes;
649+
}
650+
TradeLedger::size_type TradeLedger::cache_resident_bytes() const {
651+
return sizeof(TradeLedger) + sizeof(State)
652+
+ (state_->cache ? state_->cache_rows * kLedgerEntryBytes : 0);
653+
}
654+
TradeLedger::size_type TradeLedger::cache_size() const { return state_->cache_count; }
655+
536656
void TradeLedger::reserve(size_type) {}
537657

538658
TradeLedger::size_type TradeLedger::size() const { return state_->end; }
@@ -545,7 +665,11 @@ bool TradeLedger::empty() const { return size() == 0; }
545665

546666
Trade TradeLedger::read(size_type global) const {
547667
state_->check(global);
548-
return state_->decode(state_->descriptor(global));
668+
if (const auto* entry = state_->cached(global)) return State::decode_cached(*entry);
669+
const auto record = state_->descriptor(global);
670+
Trade row = state_->decode(record);
671+
state_->remember(global, record, row);
672+
return row;
549673
}
550674

551675
Trade TradeLedger::operator[](size_type global) const { return at(global); }
@@ -568,12 +692,17 @@ Trade TradeLedger::numeric_at(size_type global) const {
568692

569693
std::string TradeLedger::entry_id_at(size_type global) const {
570694
state_->check(global, true);
695+
if (const auto* entry = state_->cached(global))
696+
return std::string(entry->strings.data(),
697+
static_cast<size_type>(entry->record.entry_id.length));
571698
return state_->get_string(state_->descriptor(global).entry_id);
572699
}
573700

574701
void TradeLedger::replace(size_type global, const Trade& row) {
575702
state_->check(global, true);
576-
const auto record = state_->store(global, row);
703+
const auto previous = state_->descriptor(global);
704+
state_->invalidate(global);
705+
const auto record = state_->store(global, row, &previous);
577706
if (global >= state_->resident_first) state_->rows[state_->slot(global)] = record;
578707
const auto legacy = state_->materialized.find(global);
579708
if (legacy != state_->materialized.end()) legacy->second = row;
@@ -601,6 +730,7 @@ void TradeLedger::resize(size_type global_end) {
601730
if (global_end < state_->first)
602731
throw coded<std::logic_error>(RunFailureCode::engine_invariant, {},
603732
"trade ledger: rewind below resident window");
733+
state_->invalidate_cache();
604734
if (global_end < size()) {
605735
// Re-cuts may rewind far below the descriptor window. All row bytes
606736
// are already external; discard the bounded descriptor cache.
@@ -647,6 +777,7 @@ void TradeLedger::seal(size_type global_end) {
647777
if (global_end < state_->first || global_end > size())
648778
throw coded<std::logic_error>(RunFailureCode::engine_invariant, {},
649779
"trade ledger: seal outside resident window");
780+
state_->invalidate_cache();
650781
while (state_->count != 0 && state_->resident_first < global_end) state_->evict();
651782
state_->first = global_end;
652783
}

‎tests/cr150.d/p2cx-tledger.cmake‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
list(APPEND TEST_SOURCES test_p2cx_tledger_budget)
2+
pineforge_add_unit_test(test_p2cx_tledger_budget)
3+
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
4+
list(APPEND TEST_SOURCES test_p2cx_tledger_io)
5+
pineforge_add_unit_test(test_p2cx_tledger_io)
6+
endif()

0 commit comments

Comments
 (0)