unityrs_core/files/bundle/counts.rs
1//! What a bundle's block reads cost, counted as they happen (plan section
2//! 8, R2 and R3): the bytes its decodes wrote, the bytes a decode wrote
3//! only to have them dropped, the bytes it decoded again, and the bytes its
4//! cached runs hold, now and at most. [`super::BundleFile::counts`] reads
5//! them.
6//!
7//! **Cheap enough to leave on.** A decode adds to two relaxed atomics at
8//! most, and a publish updates two integers under the run index's lock,
9//! which it already holds: a count per block or per run, never per byte or
10//! per object. A build with `--cfg unityrs_no_counters` compiles every
11//! update out (the fields stay, so every charge is the same), which is how
12//! the perf bench measures what they cost (plan section 10).
13//!
14//! Each count is a snapshot of relaxed atomics: a read on another thread
15//! sees each one as some decode left it, not all of them at one instant.
16
17use std::sync::atomic::{AtomicU64, Ordering};
18
19/// What a bundle's block reads have done since it was opened (plan section
20/// 8, R2 and R3). Its own blocks only: a nested bundle counts its own.
21#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
22#[non_exhaustive]
23pub struct BundleCounts {
24 /// Every byte a block decode wrote: first decodes, measuring decodes
25 /// and decodes again, a stored block copied into a run included (the
26 /// blocks-info section is not a block).
27 pub decoded: u64,
28 /// What a decode wrote that no run kept: a block measured before a read
29 /// (it ends at or before the read's start, or every block is measured
30 /// for the total) has its output dropped, and a run decoded while
31 /// another thread published one covering it is dropped for that one.
32 pub discarded: u64,
33 /// What a decode wrote for a block an earlier decode of this open had
34 /// already decoded: a block two spans share, decoded once for each, or a
35 /// block measured earlier and decoded again into a read's run. A stored
36 /// block whose length the open took from its stored bytes
37 /// ([`crate::codec::Codecs::stores_as_is`]) is copied, not decoded, and
38 /// never counts here. Two threads that decode one block at once, before
39 /// either learns its length, each count a first decode.
40 pub redecoded: u64,
41 /// How many runs are cached now.
42 pub runs: u64,
43 /// The bytes the cached runs hold now: a decoded run's length, or a
44 /// stored run's, which is a slice of the input.
45 pub runs_held: u64,
46 /// The most bytes the cached runs held at once since the open. A
47 /// publish drops the runs the new one covers as it caches it, so the two
48 /// never count together.
49 pub runs_peak: u64,
50}
51
52const _: () = crate::send_sync::<BundleCounts>();
53
54/// The decode counts, on any thread with no lock held.
55#[derive(Debug, Default)]
56pub(super) struct DecodeCounts {
57 decoded: AtomicU64,
58 discarded: AtomicU64,
59 redecoded: AtomicU64,
60}
61
62impl DecodeCounts {
63 /// A decode wrote `bytes`; `again` when its block was decoded before.
64 pub(super) fn wrote(&self, bytes: u64, again: bool) {
65 add(&self.decoded, bytes);
66 if again {
67 add(&self.redecoded, bytes);
68 }
69 }
70
71 /// `bytes` a decode wrote were dropped unused.
72 pub(super) fn dropped(&self, bytes: u64) {
73 add(&self.discarded, bytes);
74 }
75
76 /// The counts, with the runs' (`held`).
77 pub(super) fn snapshot(&self, runs: u64, held: &RunBytes) -> BundleCounts {
78 BundleCounts {
79 decoded: self.decoded.load(Ordering::Relaxed),
80 discarded: self.discarded.load(Ordering::Relaxed),
81 redecoded: self.redecoded.load(Ordering::Relaxed),
82 runs,
83 runs_held: held.held,
84 runs_peak: held.peak,
85 }
86 }
87}
88
89/// The bytes the cached runs hold, and the most they held: kept under the
90/// run index's lock.
91#[derive(Debug, Default)]
92pub(crate) struct RunBytes {
93 held: u64,
94 peak: u64,
95}
96
97impl RunBytes {
98 /// A publish cached `added` bytes and dropped `dropped`.
99 pub(crate) fn publish(&mut self, added: u64, dropped: u64) {
100 if cfg!(not(unityrs_no_counters)) {
101 self.held = self.held.saturating_add(added).saturating_sub(dropped);
102 self.peak = self.peak.max(self.held);
103 }
104 }
105}
106
107/// Adds `n` to `counter` (relaxed): nothing reads a count to decide
108/// anything.
109fn add(counter: &AtomicU64, n: u64) {
110 if cfg!(not(unityrs_no_counters)) {
111 counter.fetch_add(n, Ordering::Relaxed);
112 }
113}