1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
//! Shared cold-start helper for the #2674/#2714 counter-guard family.
//!
//! Single-purpose companion to `common/mod.rs`, included on its own via
//! `#[path = "common/key_cache_flush.rs"] mod key_cache_flush;` so a guard file
//! pulls in ONLY this helper (not the whole `common` module, whose other utilities
//! would trip `-D warnings` dead_code in a binary that uses just this one).
/// Flush EVERY entry from the process-global B4 key→partition-offset cache
/// (issue #2059) so a counter guard that asserts a COLD "first" read (a real
/// `Index.db` probe / `Partitions.db` trie walk) starts from a genuinely empty
/// cache.
///
/// # Why this exists (issue #2674/#2714 family)
///
/// The B4 cache is a process-global singleton keyed by GENERATION IDENTITY. Every
/// `#[serial]` guard in a binary that opens the SAME on-disk fixture shares one
/// identity, so a SIBLING test that locates/point-reads a key first leaves it warm;
/// `read_work_counters::reset()` zeroes the counters but NOT the cache, so the next
/// test's "first" read is a cache HIT with zero probes and its
/// `index_probes()/trie_walks() >= 1` cold assertion fails — an execution-ORDER coin
/// flip (bare `#[serial]` lock-acquisition order is nondeterministic, biased toward
/// failure under gate CPU contention; #2714). Call this at the top of such a guard,
/// before the measured cold read, to make the cold start deterministic regardless of
/// test order. `#[allow(dead_code)]`: a binary may include this file for a subset of
/// its guards.
///
/// # Invariant — the caller AND every sibling MUST share the BARE `#[serial]` group
///
/// This is a PROCESS-GLOBAL flush. In a binary where any counter guard relies on a
/// warm cache (a "second read is a cache HIT / zero probes" assertion), a flush that
/// lands MID-un-serialized-sibling wipes that sibling's warm state and breaks its
/// assertion. So every test in a binary that calls this — and every warm-read guard
/// beside it — MUST be in ONE shared serial group so the flush can never interleave
/// with another guard's measured window.
///
/// REQUIRED GROUP: the BARE `#[serial]` (default serial-test group). All four
/// binaries that include this helper (`issue_1599_locate_parity`,
/// `issue_1570_key_offset_cache`, `issue_1574_bti_single_walk`,
/// `issue_1566_read_work_counters`) use bare `#[serial]` for EVERY test — audited in
/// #2714 roborev 1828. Do NOT introduce a keyed `#[serial(name)]` into these binaries:
/// bare `#[serial]` and `#[serial(name)]` are DIFFERENT groups that do NOT serialize
/// against each other, so a keyed test could run concurrently with a flush and
/// corrupt a sibling's warm-read assertion.