Skip to main content

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}