Skip to main content

serde_json/
counters.rs

1//! Deterministic work counters, behind the `profile` feature.
2//!
3//! A clock is the wrong primary instrument for most bricks in this crate. It
4//! needs a quiet machine, and a laptop under load reads the *same binary* half
5//! as fast as it did an hour earlier -- enough to swamp a change worth a third
6//! of a parse. A count of the work a brick removed has none of those problems:
7//! it is exact, identical on every machine under any load, needs one run rather
8//! than twenty interleaved pairs, and it says whether the optimisation is even
9//! *plugged in* -- which a byte-identical output gate cannot, because a fast
10//! path that silently stopped being taken still produces the right answer.
11//!
12//! So the order is: count the work, then confirm with the clock when the box is
13//! quiet. Never the reverse.
14//!
15//! Compiled out entirely without `profile`. With it, these add an atomic
16//! increment to some very hot paths, so **a build with them on must never
17//! produce a quoted timing**.
18
19#![allow(dead_code)]
20
21use core::sync::atomic::Ordering;
22
23/// The counter's width, chosen by what the target can actually do.
24///
25/// `AtomicU64` does not exist on a 32-bit target without 64-bit atomics --
26/// riscv32imac and riscv32imafc are two -- and this module is declared
27/// unconditionally, so importing it there failed the build outright
28/// (`unresolved import core::sync::atomic::AtomicU64`). It broke every
29/// no_std consumer of this crate on those chips.
30///
31/// Nothing is lost by narrowing: `add` only increments under `profile`,
32/// which pulls in `std`, so on a no_std target these are never written at
33/// all -- they only have to EXIST. Where 64-bit atomics are available the
34/// width is unchanged.
35#[cfg(target_has_atomic = "64")]
36pub type Counter = core::sync::atomic::AtomicU64;
37#[cfg(target_has_atomic = "64")]
38type Width = u64;
39/// A counter, 32 bits wide because the target has no 64-bit atomics.
40#[cfg(not(target_has_atomic = "64"))]
41pub type Counter = core::sync::atomic::AtomicU32;
42#[cfg(not(target_has_atomic = "64"))]
43type Width = u32;
44
45/// One counter's value, as the reported 64-bit type.
46///
47/// Split per width so that neither arm converts a type to itself: clippy's
48/// `useless_conversion` and `unnecessary_cast` each object to one of the
49/// single-expression spellings.
50#[cfg(target_has_atomic = "64")]
51#[inline]
52fn get(counter: &Counter) -> u64 {
53    counter.load(Ordering::Relaxed)
54}
55
56/// One counter's value, widened from the narrow counter this target uses.
57#[cfg(not(target_has_atomic = "64"))]
58#[inline]
59fn get(counter: &Counter) -> u64 {
60    u64::from(counter.load(Ordering::Relaxed))
61}
62
63/// Calls to `Read::peek`.
64pub static PEEK: Counter = Counter::new(0);
65/// Calls to `Read::next`.
66pub static NEXT: Counter = Counter::new(0);
67/// Calls to `Read::discard`.
68pub static DISCARD: Counter = Counter::new(0);
69/// Calls to `Read::skip_whitespace` -- whitespace runs considered.
70pub static WS_RUNS: Counter = Counter::new(0);
71/// Insignificant whitespace bytes skipped.
72pub static WS_BYTES: Counter = Counter::new(0);
73/// Calls to `Read::take_8_digits`.
74pub static D8_CALLS: Counter = Counter::new(0);
75/// Calls to `Read::take_8_digits` that consumed eight digits.
76pub static D8_HITS: Counter = Counter::new(0);
77/// Calls to `SliceRead::skip_to_escape` -- string runs considered (brick B2).
78pub static STR_SCANS: Counter = Counter::new(0);
79/// String content bytes advanced over by the escape scanner (brick B2).
80pub static STR_BYTES: Counter = Counter::new(0);
81/// Strings that had to be copied into scratch because they held an escape, so
82/// the zero-copy borrow was lost (brick B2: this is the cost worth removing).
83pub static STR_COPIES: Counter = Counter::new(0);
84/// Strings returned as a borrow of the input, the fast path (brick B2).
85pub static STR_BORROWS: Counter = Counter::new(0);
86/// String content bytes examined by the serializer's escape loop (brick B3).
87pub static ESC_BYTES: Counter = Counter::new(0);
88/// Bytes that actually needed a JSON escape (brick B3). The ratio of this to
89/// `ESC_BYTES` is what a per-chunk mask would be skipping over.
90pub static ESC_HITS: Counter = Counter::new(0);
91/// `write_string_fragment` calls: clean runs handed to the writer (brick B3).
92pub static ESC_FRAGS: Counter = Counter::new(0);
93/// Steps taken by the escape scanner: one per 8-byte chunk on the wide path,
94/// one per byte on the scalar path (brick B3). This is the counter that says
95/// whether the wide path is ENGAGED -- a byte-identical output gate cannot,
96/// because a fast path that silently stopped being taken still produces the
97/// right answer. Expect roughly `esc_bytes / 8` wide and `esc_bytes` scalar.
98pub static ESC_STEPS: Counter = Counter::new(0);
99/// Object keys parsed (brick B6). One per key, whatever the visitor does next.
100pub static KEYS: Counter = Counter::new(0);
101/// `RawValue` captures completed on a reader (brick B13).
102pub static RAW_CAPTURES: Counter = Counter::new(0);
103/// Bytes of `RawValue` text captured on a reader (brick B13). Upstream pushed
104/// one byte at a time and this is how many; B13 takes the same total in
105/// `RAW_CAPTURES` copies, so the ratio of the two is the brick's whole effect.
106pub static RAW_BYTES: Counter = Counter::new(0);
107/// Times the window had to GROW because a captured value was longer than it
108/// (brick B13). Zero on any stream of ordinary documents; non-zero is the only
109/// case where B13 costs memory that upstream did not spend.
110pub static RAW_GROWS: Counter = Counter::new(0);
111/// Times a grown window was handed back at the end of a capture (brick B13).
112/// This is the counter that says the growth is not permanent -- there is no
113/// output difference to gate it with.
114pub static RAW_SHRINKS: Counter = Counter::new(0);
115/// Bytes handed to `str::from_utf8` for validation (brick B12). `from_str`
116/// pays none of this because its input is already known to be UTF-8, so the
117/// gap between `from_slice` and `from_str` on the same bytes is B12's ceiling.
118pub static UTF8_BYTES: Counter = Counter::new(0);
119/// Calls to that validation (brick B12).
120pub static UTF8_CALLS: Counter = Counter::new(0);
121
122/// A reading of every counter.
123#[derive(#[automatically_derived]
#[doc(hidden)]
unsafe impl ::core::clone::TrivialClone for Counters { }
#[automatically_derived]
impl ::core::clone::Clone for Counters {
    #[inline]
    fn clone(&self) -> Self {
        let _: ::core::clone::AssertParamIsClone<u64>;
        *self
    }
}Clone, #[automatically_derived]
impl ::core::marker::Copy for Counters { }Copy, #[automatically_derived]
impl ::core::fmt::Debug for Counters {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        let names: &'static _ =
            &["peek", "next", "discard", "ws_runs", "ws_bytes", "d8_calls",
                        "d8_hits", "str_scans", "str_bytes", "str_copies",
                        "str_borrows", "esc_bytes", "esc_hits", "esc_frags",
                        "esc_steps", "keys", "raw_captures", "raw_bytes",
                        "raw_grows", "raw_shrinks", "utf8_bytes", "utf8_calls"];
        let values: &[&dyn ::core::fmt::Debug] =
            &[&self.peek, &self.next, &self.discard, &self.ws_runs,
                        &self.ws_bytes, &self.d8_calls, &self.d8_hits,
                        &self.str_scans, &self.str_bytes, &self.str_copies,
                        &self.str_borrows, &self.esc_bytes, &self.esc_hits,
                        &self.esc_frags, &self.esc_steps, &self.keys,
                        &self.raw_captures, &self.raw_bytes, &self.raw_grows,
                        &self.raw_shrinks, &self.utf8_bytes, &&self.utf8_calls];
        ::core::fmt::Formatter::debug_struct_fields_finish(f, "Counters",
            names, values)
    }
}Debug, #[automatically_derived]
impl ::core::default::Default for Counters {
    #[inline]
    fn default() -> Self {
        Counters {
            peek: ::core::default::Default::default(),
            next: ::core::default::Default::default(),
            discard: ::core::default::Default::default(),
            ws_runs: ::core::default::Default::default(),
            ws_bytes: ::core::default::Default::default(),
            d8_calls: ::core::default::Default::default(),
            d8_hits: ::core::default::Default::default(),
            str_scans: ::core::default::Default::default(),
            str_bytes: ::core::default::Default::default(),
            str_copies: ::core::default::Default::default(),
            str_borrows: ::core::default::Default::default(),
            esc_bytes: ::core::default::Default::default(),
            esc_hits: ::core::default::Default::default(),
            esc_frags: ::core::default::Default::default(),
            esc_steps: ::core::default::Default::default(),
            keys: ::core::default::Default::default(),
            raw_captures: ::core::default::Default::default(),
            raw_bytes: ::core::default::Default::default(),
            raw_grows: ::core::default::Default::default(),
            raw_shrinks: ::core::default::Default::default(),
            utf8_bytes: ::core::default::Default::default(),
            utf8_calls: ::core::default::Default::default(),
        }
    }
}Default, #[automatically_derived]
impl ::core::marker::StructuralPartialEq for Counters { }
#[automatically_derived]
impl ::core::cmp::PartialEq for Counters {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.peek == other.peek && self.next == other.next &&
                                                                                        self.discard == other.discard &&
                                                                                    self.ws_runs == other.ws_runs &&
                                                                                self.ws_bytes == other.ws_bytes &&
                                                                            self.d8_calls == other.d8_calls &&
                                                                        self.d8_hits == other.d8_hits &&
                                                                    self.str_scans == other.str_scans &&
                                                                self.str_bytes == other.str_bytes &&
                                                            self.str_copies == other.str_copies &&
                                                        self.str_borrows == other.str_borrows &&
                                                    self.esc_bytes == other.esc_bytes &&
                                                self.esc_hits == other.esc_hits &&
                                            self.esc_frags == other.esc_frags &&
                                        self.esc_steps == other.esc_steps && self.keys == other.keys
                                && self.raw_captures == other.raw_captures &&
                            self.raw_bytes == other.raw_bytes &&
                        self.raw_grows == other.raw_grows &&
                    self.raw_shrinks == other.raw_shrinks &&
                self.utf8_bytes == other.utf8_bytes &&
            self.utf8_calls == other.utf8_calls
    }
}PartialEq, #[automatically_derived]
impl ::core::cmp::Eq for Counters {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {
        let _: ::core::cmp::AssertParamIsEq<u64>;
    }
}Eq)]
124#[non_exhaustive]
125pub struct Counters {
126    /// Calls to `Read::peek`.
127    pub peek: u64,
128    /// Calls to `Read::next`.
129    pub next: u64,
130    /// Calls to `Read::discard`.
131    pub discard: u64,
132    /// Whitespace runs considered.
133    pub ws_runs: u64,
134    /// Insignificant whitespace bytes skipped.
135    pub ws_bytes: u64,
136    /// Calls to `take_8_digits`.
137    pub d8_calls: u64,
138    /// Calls to `take_8_digits` that consumed eight digits.
139    pub d8_hits: u64,
140    /// String runs considered by the escape scanner.
141    pub str_scans: u64,
142    /// String content bytes advanced over by the escape scanner.
143    pub str_bytes: u64,
144    /// Strings copied into scratch because they held an escape.
145    pub str_copies: u64,
146    /// Strings returned as a borrow of the input.
147    pub str_borrows: u64,
148    /// String content bytes examined by the serializer's escape loop.
149    pub esc_bytes: u64,
150    /// Bytes that needed a JSON escape.
151    pub esc_hits: u64,
152    /// Clean runs handed to the writer.
153    pub esc_frags: u64,
154    /// Steps taken by the escape scanner (per chunk wide, per byte scalar).
155    pub esc_steps: u64,
156    /// Object keys parsed.
157    pub keys: u64,
158    /// `RawValue` captures completed on a reader.
159    pub raw_captures: u64,
160    /// Bytes of `RawValue` text captured on a reader.
161    pub raw_bytes: u64,
162    /// Times the window grew for a capture longer than itself.
163    pub raw_grows: u64,
164    /// Times a grown window was handed back.
165    pub raw_shrinks: u64,
166    /// Bytes handed to `str::from_utf8` for validation.
167    pub utf8_bytes: u64,
168    /// Calls to that validation.
169    pub utf8_calls: u64,
170}
171
172/// Read every counter.
173#[must_use]
174pub fn snapshot() -> Counters {
175    Counters {
176        peek: get(&PEEK),
177        next: get(&NEXT),
178        discard: get(&DISCARD),
179        ws_runs: get(&WS_RUNS),
180        ws_bytes: get(&WS_BYTES),
181        d8_calls: get(&D8_CALLS),
182        d8_hits: get(&D8_HITS),
183        str_scans: get(&STR_SCANS),
184        str_bytes: get(&STR_BYTES),
185        str_copies: get(&STR_COPIES),
186        str_borrows: get(&STR_BORROWS),
187        esc_bytes: get(&ESC_BYTES),
188        esc_hits: get(&ESC_HITS),
189        esc_frags: get(&ESC_FRAGS),
190        esc_steps: get(&ESC_STEPS),
191        keys: get(&KEYS),
192        raw_captures: get(&RAW_CAPTURES),
193        raw_bytes: get(&RAW_BYTES),
194        raw_grows: get(&RAW_GROWS),
195        raw_shrinks: get(&RAW_SHRINKS),
196        utf8_bytes: get(&UTF8_BYTES),
197        utf8_calls: get(&UTF8_CALLS),
198    }
199}
200
201/// Zero every counter.
202pub fn reset() {
203    for c in [
204        &PEEK,
205        &NEXT,
206        &DISCARD,
207        &WS_RUNS,
208        &WS_BYTES,
209        &D8_CALLS,
210        &D8_HITS,
211        &STR_SCANS,
212        &STR_BYTES,
213        &STR_COPIES,
214        &STR_BORROWS,
215        &ESC_BYTES,
216        &ESC_HITS,
217        &ESC_FRAGS,
218        &ESC_STEPS,
219        &KEYS,
220        &RAW_CAPTURES,
221        &RAW_BYTES,
222        &RAW_GROWS,
223        &RAW_SHRINKS,
224        &UTF8_BYTES,
225        &UTF8_CALLS,
226    ] {
227        c.store(0, Ordering::Relaxed);
228    }
229}
230
231impl Counters {
232    /// What happened between two readings.
233    #[must_use]
234    pub fn since(self, earlier: Counters) -> Counters {
235        Counters {
236            peek: self.peek - earlier.peek,
237            next: self.next - earlier.next,
238            discard: self.discard - earlier.discard,
239            ws_runs: self.ws_runs - earlier.ws_runs,
240            ws_bytes: self.ws_bytes - earlier.ws_bytes,
241            d8_calls: self.d8_calls - earlier.d8_calls,
242            d8_hits: self.d8_hits - earlier.d8_hits,
243            str_scans: self.str_scans - earlier.str_scans,
244            str_bytes: self.str_bytes - earlier.str_bytes,
245            str_copies: self.str_copies - earlier.str_copies,
246            str_borrows: self.str_borrows - earlier.str_borrows,
247            esc_bytes: self.esc_bytes - earlier.esc_bytes,
248            esc_hits: self.esc_hits - earlier.esc_hits,
249            esc_frags: self.esc_frags - earlier.esc_frags,
250            esc_steps: self.esc_steps - earlier.esc_steps,
251            keys: self.keys - earlier.keys,
252            raw_captures: self.raw_captures - earlier.raw_captures,
253            raw_bytes: self.raw_bytes - earlier.raw_bytes,
254            raw_grows: self.raw_grows - earlier.raw_grows,
255            raw_shrinks: self.raw_shrinks - earlier.raw_shrinks,
256            utf8_bytes: self.utf8_bytes - earlier.utf8_bytes,
257            utf8_calls: self.utf8_calls - earlier.utf8_calls,
258        }
259    }
260}
261
262/// Which SIMD rung the byte scanners are actually running.
263///
264/// Belongs on every method line that quotes a scan: `"avx2"`, `"sse2"`,
265/// `"swar"` or `"scalar"`, honouring `RJT_ISA`. Returns `"swar"` when the
266/// island is not linked at all, which is what the crate then does.
267#[must_use]
268pub fn isa() -> &'static str {
269    #[cfg(feature = "accel")]
270    {
271        rusty_json_turbo_accel::isa().name()
272    }
273    #[cfg(not(feature = "accel"))]
274    {
275        "swar"
276    }
277}
278
279/// The widest rung this machine could offer, whatever `RJT_ISA` asked for.
280///
281/// Printed beside [`isa`] so a run that was narrowed by an override is
282/// distinguishable from one on a machine that has nothing wider -- two very
283/// different reasons for the same number.
284#[must_use]
285pub fn isa_available() -> &'static str {
286    #[cfg(feature = "accel")]
287    {
288        rusty_json_turbo_accel::isa_available().name()
289    }
290    #[cfg(not(feature = "accel"))]
291    {
292        "swar"
293    }
294}
295
296/// Whether this build carries the counters, so a caller cannot read a zero as
297/// "no work happened" when it means "nothing was counted".
298#[must_use]
299pub const fn enabled() -> bool {
300    falsecfg!(feature = "profile")
301}
302
303/// Whether the optional SIMD island is linked (the `accel` feature).
304///
305/// [`isa`] cannot answer this. Off `x86_64` the island's own answer is
306/// `"swar"`, which is exactly what the in-crate SWAR reports, so the two
307/// configurations are indistinguishable by ISA name alone.
308///
309/// **It has to be distinguishable, because one counter means two things.**
310/// [`ESC_STEPS`] is incremented by this crate's escape scanner once per 8-byte
311/// chunk, and by the island once per CALL -- the island is a separate `no_std`
312/// crate with no access to these statics, so it cannot count chunks even in
313/// principle. Measured on `twitter`, the same document reads 101,382 steps
314/// without the island and 19,327 with it: about one per string rather than one
315/// per chunk. A census that did not know which build it was looking at would
316/// read the second as a nineteen-byte step and conclude something impossible.
317///
318/// Found by `tests/m6_arch_census.rs` failing on exactly that.
319#[must_use]
320pub const fn accel_linked() -> bool {
321    falsecfg!(feature = "accel")
322}
323
324/// Add to a counter. Compiles to nothing without `profile`.
325#[inline(always)]
326pub fn add(counter: &Counter, by: u64) {
327    #[cfg(all(feature = "profile", target_has_atomic = "64"))]
328    counter.fetch_add(by, Ordering::Relaxed);
329    // saturating rather than wrapping: on a narrow counter a wrap would be a
330    // silently wrong number, and a counter is only ever read as a total
331    #[cfg(all(feature = "profile", not(target_has_atomic = "64")))]
332    counter.fetch_add(Width::try_from(by).unwrap_or(Width::MAX), Ordering::Relaxed);
333    #[cfg(not(feature = "profile"))]
334    {
335        let _ = (counter, by);
336    }
337}