perf: add SIMD integer formatting paths

.github/workflows/ci.yml

@@ -37,6 +37,11 @@ jobs:
       - run: cargo build
       - run: cargo test
       - run: cargo test --release
+      - name: Test SIMD formatting path
+        run: cargo test --release
+        if: matrix.rust == 'stable'
+        env:
+          RUSTFLAGS: -Dwarnings -C target-feature=+sse4.1,+lzcnt
       - run: cargo build --no-default-features
       - run: cargo test --tests --no-default-features
       - run: cargo test --tests --no-default-features --release

Cargo.toml

@@ -17,11 +17,16 @@ no-panic = { version = "0.1", optional = true }
 
 [target.'cfg(not(miri))'.dev-dependencies]
 criterion = { version = "0.8", default-features = false }
+gungraun = "=0.18.2"
 
 [[bench]]
 name = "bench"
 harness = false
 
+[[bench]]
+name = "gungraun"
+harness = false
+
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]
 rustdoc-args = [

README.md

@@ -47,6 +47,28 @@ library.
 
 ![performance](https://raw.githubusercontent.com/dtolnay/itoa/master/itoa-benchmark.png)
 
+This repository also contains Criterion and Gungraun microbenchmarks. Run the
+Gungraun benchmarks with:
+
+```console
+cargo install --version 0.18.2 gungraun-runner
+cargo bench --bench gungraun
+```
+
+Gungraun requires Valgrind to be installed.
+On x86-64, the SIMD-optimized path is gated on the `sse4.1` and `lzcnt`
+target features. Enable exactly those to benchmark it:
+
+```console
+RUSTFLAGS="-C target-feature=+sse4.1,+lzcnt" cargo bench --bench gungraun
+```
+
+Do not use `-C target-cpu=native` here. On AVX-512-capable CPUs (for example
+AMD Zen 4/5) it lets the compiler autovectorize the digit conversion into
+EVEX-encoded AVX-512 instructions, which Valgrind cannot decode and which make
+Gungraun abort with `SIGILL`. The `+sse4.1,+lzcnt` feature set exercises the
+same optimized code without emitting instructions Valgrind rejects.
+
 <br>
 
 #### License

benches/gungraun.rs

@@ -0,0 +1,80 @@
+use gungraun::prelude::*;
+use std::hint;
+use std::io::Write;
+
+macro_rules! benchmarks {
+    (
+        $itoa:ident,
+        $std_fmt:ident,
+        $setup_std_fmt:ident,
+        $ty:ty,
+        $($id:ident => $value:expr),+ $(,)?
+    ) => {
+        fn $setup_std_fmt(value: $ty) -> (Vec<u8>, $ty) {
+            (
+                Vec::with_capacity(<$ty as itoa::Integer>::MAX_STR_LEN),
+                value,
+            )
+        }
+
+        #[library_benchmark]
+        $(
+            #[bench::$id($value)]
+        )+
+        fn $itoa(int: $ty) -> usize {
+            let mut buf = itoa::Buffer::new();
+            let formatted = buf.format(hint::black_box(int));
+            hint::black_box(formatted).len()
+        }
+
+        #[library_benchmark]
+        $(
+            #[bench::$id(args = ($value), setup = $setup_std_fmt)]
+        )+
+        fn $std_fmt((mut buf, int): (Vec<u8>, $ty)) -> usize {
+            write!(&mut buf, "{}", hint::black_box(int)).unwrap();
+            hint::black_box(buf.as_slice()).len()
+        }
+    };
+}
+
+benchmarks!(
+    itoa_u64,
+    std_fmt_u64,
+    setup_std_fmt_u64,
+    u64,
+    zero => 0,
+    half => u64::from(u32::MAX),
+    max => u64::MAX,
+);
+
+benchmarks!(
+    itoa_i16,
+    std_fmt_i16,
+    setup_std_fmt_i16,
+    i16,
+    zero => 0,
+    min => i16::MIN,
+);
+
+benchmarks!(
+    itoa_u128,
+    std_fmt_u128,
+    setup_std_fmt_u128,
+    u128,
+    zero => 0,
+    max => u128::MAX,
+);
+
+library_benchmark_group!(
+    name = benches;
+    benchmarks =
+        itoa_u64,
+        std_fmt_u64,
+        itoa_i16,
+        std_fmt_i16,
+        itoa_u128,
+        std_fmt_u128
+);
+
+main!(library_benchmark_groups = benches);