Skip to main content

rusty_json_turbo_accel/
lib.rs

1//! The SIMD island: SSE2 and AVX2 twins of the JSON byte scanners.
2//!
3//! # Why this is a separate crate
4//!
5//! Vector intrinsics are `unsafe`, and the workspace denies `unsafe_code`
6//! everywhere else. Rather than open a hole in the parser, the vector code
7//! lives here, alone, so `rusty_json_turbo` can keep tightening toward
8//! `forbid(unsafe_code)` while still reaching a wide scan. Every `unsafe` in
9//! this crate is a load or a compare, each one bounds-checked by the caller
10//! immediately above it and carrying its invariant in a `SAFETY` comment.
11//!
12//! There are no dependencies and no build script. That is a contract, not an
13//! accident: `rusty_json_turbo` advertises an empty dependency tree.
14//!
15//! # The rule every kernel here follows
16//!
17//! **The scalar version is written first, it is the oracle, and it stays in
18//! the tree forever.** Each vector kernel is tested against it over every one
19//! of the 256 byte values at every offset, and `RJT_ISA=scalar` runs it in
20//! production so the two can be compared inside one binary. A vector kernel
21//! whose scalar twin has been deleted cannot be checked and cannot be
22//! debugged.
23//!
24//! # What the corpus said before any of this was written
25//!
26//! Sizing a kernel is a measurement, not a preference for the widest register
27//! available. On JSONCORP, whitespace runs are 16 to 29 bytes on
28//! `citm_catalog` and **nothing in the corpus reaches 32 bytes**, so no
29//! 32-byte step is ever fully used. That does not make AVX2 worthless -- a
30//! wide load that overshoots the end of a run still resolves it in one
31//! iteration -- but it does mean the honest figure is steps taken, not bytes
32//! covered: 8-byte steps 140,381, 16-byte 95,424, 32-byte 50,467 on
33//! `citm_catalog`, and 16,252 against 15,476 on `twitter`, which is nothing.
34//!
35//! So the whitespace kernel is a `citm_catalog` win and `twitter` is a
36//! CONTROL. That distinction was paid for once already: brick B1s cost
37//! `twitter` 10% by taking an 8-byte step over its 1-byte runs, until a
38//! 4-byte scalar peel was put in front.
39
40#![no_std]
41// THE ONE PLACE IN THE WORKSPACE WHERE THIS IS ALLOWED. Vector intrinsics are
42// unsafe functions and unaligned loads are unsafe operations; there is no safe
43// spelling of either. Every block below is individually justified.
44#![allow(unsafe_code)]
45
46#[cfg(feature = "std")]
47extern crate std;
48
49/// Which instruction set the scanners will actually use.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum Isa {
52    /// The oracle. Always available, always correct, and reachable in
53    /// production through `RJT_ISA=scalar`.
54    Scalar,
55    /// 8 bytes per step with ordinary integer arithmetic. No target feature,
56    /// so this is the floor on every architecture.
57    Swar,
58    /// 16 bytes per step. Baseline on `x86_64`, so it needs no runtime
59    /// detection there.
60    Sse2,
61    /// 32 bytes per step. Detected at runtime; needs `std`.
62    Avx2,
63}
64
65impl Isa {
66    /// The name used by `RJT_ISA` and printed in a method line.
67    #[must_use]
68    pub fn name(self) -> &'static str {
69        match self {
70            Isa::Scalar => "scalar",
71            Isa::Swar => "swar",
72            Isa::Sse2 => "sse2",
73            Isa::Avx2 => "avx2",
74        }
75    }
76
77    /// Bytes examined per step. The number that prices the kernel.
78    #[must_use]
79    pub fn step(self) -> usize {
80        match self {
81            Isa::Scalar => 1,
82            Isa::Swar => 8,
83            Isa::Sse2 => 16,
84            Isa::Avx2 => 32,
85        }
86    }
87}
88
89/// A scanner kernel: index of the first interesting byte at or after `from`.
90///
91/// Named so the twin tests can hold a table of them without tripping the
92/// complex-type lint, and so every kernel is forced into one shape.
93pub type Scanner = fn(&[u8], usize) -> usize;
94
95mod dispatch;
96mod escape;
97mod whitespace;
98
99pub use dispatch::{isa, isa_available};
100pub use escape::{first_escape, first_escape_scalar, needs_escape};
101pub use whitespace::{first_non_ws, first_non_ws_scalar, is_ws};
102
103#[cfg(test)]
104mod tests;