perf: Rust decoder 30% faster than C++, and NO unsafe (#69)

* improve rust decoder by 100x+ -- was massively slower due to
un-inlined decoding bit functions
* bump version to 0.8.1
* some minor just file cleanup
* improve readme

---------

Co-authored-by: Frank Elsinga <frank@elsinga.de>

Author: nyurik

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fastpfor"
-version = "0.8.0"
+version = "0.8.1"
 description = "FastPFOR lib with C++ Rust wrapper and pure Rust implementation"
 authors = [
     "Francisco Jimenez <jjcfrank@gmail.com>",
@@ -24,17 +24,18 @@ harness = false
 [features]
 # Eventually we may want to build without the C++ bindings by default.
 # Keeping it on for now to simplify development.
-default = ["cpp"]
+default = ["cpp", "rust"]
 # Used internally for testing and benchmarking. Not intended for public use.
 _all_compatible = ["cpp_portable", "rust"]
 # Use portable C++ code that will not rely on the latest CPU features. This is the default for the C++ bindings.
 cpp_portable = ["cpp"]
 # Optimize FastPFOR for the current CPU.
 cpp_native = ["cpp"]
 cpp = ["dep:cmake", "dep:cxx", "dep:cxx-build"]
-rust = ["dep:thiserror", "dep:bytes"]
+rust = ["dep:thiserror", "dep:bytes", "dep:bytemuck"]
 
 [dependencies]
+bytemuck = { version = "1.25.0", optional = true }
 bytes = { version = "1.11", optional = true }
 cxx = { version = "1.0.194", optional = true }
 thiserror = { version = "2.0.18", optional = true }

README.md

@@ -6,7 +6,9 @@
 [![license](https://img.shields.io/crates/l/fastpfor.svg)](https://github.com/jjcfrancisco/fastpfor/blob/main/LICENSE-APACHE)
 [![CI build](https://github.com/jjcfrancisco/fastpfor/actions/workflows/ci.yml/badge.svg)](https://github.com/jjcfrancisco/fastpfor/actions)
 
-This is a Rust wrapper for the [C++ FastPFor library](https://github.com/fast-pack/FastPFor), as well as a pure Rust re-implementation (work in progress).  Supports 32-bit and 64-bit integers, and SIMD-optimized codecs for 128-bit and 256-bit vectors. Based on the [Decoding billions of integers per second through vectorization, 2012](https://arxiv.org/abs/1209.2137) paper.
+This is a Rust wrapper for the [C++ FastPFor library](https://github.com/fast-pack/FastPFor), as well as a pure Rust re-implementation.  Supports 32-bit and 64-bit integers, and SIMD-optimized codecs for 128-bit and 256-bit vectors. Based on the [Decoding billions of integers per second through vectorization, 2012](https://arxiv.org/abs/1209.2137) paper.
+
+The Rust **decoder** is about 29% faster than the C++ version. The Rust implementation contains no `unsafe` code, and when built without the `cpp` feature this crate has `#![forbid(unsafe_code)]`.
 
 ### Supported algorithms
 Unless otherwise specified, all codecs support `&[u32]` only.
@@ -45,11 +47,31 @@ Unless otherwise specified, all codecs support `&[u32]` only.
 * VarIntGb
 ```
 
+## Benchmarks
+### Decoding
+
+Using Linux x86-64 running `just bench::cpp-vs-rust-decode native`. The values below are time measurements; smaller values indicate faster decoding.
+
+| name                                    | cpp (ns) | rust (ns) | % faster |
+|-----------------------------------------|----------|-----------|----------|
+| `clustered/1024`                        | 643.24   | 392.93    | 38.91%   |
+| `clustered/4096`                        | 1986     | 1414.8    | 28.76%   |
+| `sequential/1024`                       | 653.69   | 396.02    | 39.42%   |
+| `sequential/4096`                       | 2106     | 1476.2    | 29.91%   |
+| `sparse/1024`                           | 428.8    | 352.38    | 17.82%   |
+| `sparse/4096`                           | 1114     | 1179.5    | -5.88%   |
+| `uniform_large_value_distribution/1024` | 286.74   | 153.06    | 46.62%   |
+| `uniform_large_value_distribution/4096` | 748.19   | 558.05    | 25.41%   |
+| `uniform_small_value_distribution/1024` | 606.4    | 405.44    | 33.14%   |
+| `uniform_small_value_distribution/4096` | 2017.3   | 1403.7    | 30.42%   |
+
+Rust Encoding has not yet been either optimized or even fully verified.
+
 ## Usage
 
 ### Crate Features
-* `cpp` - C++ implementation (default, uses portable SIMD mode)
-* `rust` - Rust implementation (work in progress, opt-in)
+* `cpp` - C++ implementation (uses portable SIMD mode)
+* `rust` - Rust implementation (safe Rust code, no `unsafe` blocks)
 
 #### SIMD Mode Configuration
 

benches/fastpfor_benchmark.rs

@@ -117,9 +117,8 @@ fn prepare_compressed_data(data: &[u32], block_size: NonZeroU32) -> Vec<u32> {
     compressed
 }
 
-/// Helper function to decompress data
-fn decompress_data(codec: &mut FastPFOR, compressed: &[u32], original_size: usize) -> usize {
-    let mut decompressed = vec![0u32; original_size];
+/// The caller must ensure that the `decompressed` slice is large enough to hold the output.
+fn decompress_data(codec: &mut FastPFOR, compressed: &[u32], decompressed: &mut [u32]) -> usize {
     let mut input_offset = Cursor::new(0);
     let mut output_offset = Cursor::new(0);
 
@@ -128,7 +127,7 @@ fn decompress_data(codec: &mut FastPFOR, compressed: &[u32], original_size: usiz
             compressed,
             compressed.len() as u32,
             &mut input_offset,
-            &mut decompressed,
+            decompressed,
             &mut output_offset,
         )
         .unwrap();
@@ -158,10 +157,8 @@ fn benchmark_compression(c: &mut Criterion) {
             let data = generator(size);
             group.throughput(Throughput::Elements(size as u64));
             group.bench_with_input(BenchmarkId::new(*name, size), &data, |b, data| {
-                b.iter(|| {
-                    let mut codec = FastPFOR::default();
-                    black_box(compress_data(&mut codec, black_box(data)))
-                });
+                let mut codec = FastPFOR::default();
+                b.iter(|| black_box(compress_data(&mut codec, black_box(data))));
             });
         }
     }
@@ -196,9 +193,14 @@ fn benchmark_decompression(c: &mut Criterion) {
                 BenchmarkId::new(*name, size),
                 &(compressed, size),
                 |b, (compressed, size)| {
+                    let mut codec = FastPFOR::new(DEFAULT_PAGE_SIZE, BLOCK_SIZE_128);
+                    let mut decompressed = vec![0u32; *size];
                     b.iter(|| {
-                        let mut codec = FastPFOR::default();
-                        black_box(decompress_data(&mut codec, black_box(compressed), *size))
+                        black_box(decompress_data(
+                            &mut codec,
+                            black_box(compressed),
+                            &mut decompressed,
+                        ))
                     });
                 },
             );
@@ -219,11 +221,11 @@ fn benchmark_roundtrip(c: &mut Criterion) {
             BenchmarkId::new("compress_decompress", size),
             &data,
             |b, data| {
+                let mut codec1 = FastPFOR::default();
+                let mut codec2 = FastPFOR::default();
+                let mut compressed = vec![0u32; data.len() * 2];
+                let mut decompressed = vec![0u32; data.len()];
                 b.iter(|| {
-                    let mut codec1 = FastPFOR::default();
-                    let mut codec2 = FastPFOR::default();
-                    let mut compressed = vec![0u32; data.len() * 2];
-                    let mut decompressed = vec![0u32; data.len()];
                     let mut input_offset = Cursor::new(0);
                     let mut output_offset = Cursor::new(0);
 
@@ -285,8 +287,13 @@ fn benchmark_block_sizes(c: &mut Criterion) {
         group.throughput(Throughput::Elements(size as u64));
         group.bench_function(format!("decompress_{block_size}"), |b| {
             let mut codec = FastPFOR::new(DEFAULT_PAGE_SIZE, block_size);
+            let mut decompressed = vec![0u32; size];
             b.iter(|| {
-                black_box(decompress_data(&mut codec, black_box(&compressed), size));
+                black_box(decompress_data(
+                    &mut codec,
+                    black_box(&compressed),
+                    &mut decompressed,
+                ));
             });
         });
     }
@@ -317,8 +324,8 @@ fn benchmark_compression_ratio(c: &mut Criterion) {
     for (name, data_fn) in patterns {
         let data = data_fn(size);
         group.bench_function(*name, |b| {
+            let mut codec = FastPFOR::default();
             b.iter(|| {
-                let mut codec = FastPFOR::default();
                 let compressed_size = compress_data(&mut codec, black_box(&data));
                 #[expect(
                     clippy::cast_precision_loss,
@@ -429,7 +436,14 @@ fn benchmark_cpp_vs_rust(c: &mut Criterion) {
                 &rust_compressed,
                 |b, compressed| {
                     let mut codec = FastPFOR::new(DEFAULT_PAGE_SIZE, BLOCK_SIZE_128);
-                    b.iter(|| black_box(decompress_data(&mut codec, black_box(compressed), size)));
+                    let mut decompressed = vec![0u32; size];
+                    b.iter(|| {
+                        black_box(decompress_data(
+                            &mut codec,
+                            black_box(compressed),
+                            &mut decompressed,
+                        ))
+                    });
                 },
             );
         }

fuzz/justfile

@@ -0,0 +1,44 @@
+#!/usr/bin/env just --justfile
+# Fuzz testing recipes. All commands must be run from the repo root:
+#   just fuzz::run rust_compress_oracle
+# cargo-fuzz requires nightly Rust and must be run from inside the fuzz/ directory.
+
+fuzz_dir := justfile_directory()
+
+# List available fuzz targets
+list:
+    @cd {{fuzz_dir}} && cargo +nightly fuzz list
+
+# Run a fuzz target indefinitely  (Ctrl-C to stop)
+# Targets: rust_compress_oracle, rust_decompress_oracle, cpp_roundtrip
+run target *args:
+    cd {{fuzz_dir}} && cargo +nightly fuzz run --target x86_64-unknown-linux-gnu {{target}} {{args}}
+
+# Run a fuzz target for a fixed number of seconds
+run-time target seconds='60' *args:
+    cd {{fuzz_dir}} && cargo +nightly fuzz run {{target}} {{args}} -- -max_total_time={{seconds}}
+
+# Run a fuzz target for a fixed number of iterations
+run-iters target iters='10000' *args:
+    cd {{fuzz_dir}} && cargo +nightly fuzz run {{target}} {{args}} -- -runs={{iters}}
+
+# Run rust_compress_oracle (Rust only, no C++ required)
+rust-compress *args: (run 'rust_compress_oracle' args)
+
+# Run rust_decompress_oracle (uses C++ as oracle)
+rust-decompress *args: (run 'rust_decompress_oracle' args)
+
+# Run cpp_roundtrip (C++ roundtrip)
+cpp-roundtrip *args: (run 'cpp_roundtrip' args)
+
+# Reproduce a specific crash artifact
+repro target artifact:
+    cd {{fuzz_dir}} && cargo +nightly fuzz run {{target}} {{artifact}}
+
+# Build all fuzz targets without running them
+build:
+    cd {{fuzz_dir}} && cargo +nightly fuzz build --target x86_64-unknown-linux-gnu
+
+# Print coverage for a fuzz target (requires llvm-tools)
+coverage target:
+    cd {{fuzz_dir}} && cargo +nightly fuzz coverage --target x86_64-unknown-linux-gnu {{target}}

justfile

@@ -15,6 +15,7 @@ export RUSTDOCFLAGS := env('RUSTDOCFLAGS', if ci_mode == '1' {'-D warnings'} els
 export RUST_BACKTRACE := env('RUST_BACKTRACE', if ci_mode == '1' {'1'} else {'0'})
 
 mod bench 'benches/justfile'
+mod fuzz 'fuzz/justfile'
 
 @_default:
     {{just}} --list
@@ -30,6 +31,8 @@ build:
 # Quick compile without building a binary
 check:
     cargo check --workspace --all-targets --features _all_compatible
+    cargo check --workspace --all-targets --no-default-features --features cpp
+    cargo check --workspace --all-targets --no-default-features --features rust
 
 # Generate code coverage report to upload to codecov.io
 ci-coverage: env-info && \
@@ -38,7 +41,7 @@ ci-coverage: env-info && \
     mkdir -p target/llvm-cov
 
 # Run all tests as expected by CI
-ci-test: env-info test-fmt build clippy test test-doc && assert-git-is-clean
+ci-test: env-info test-fmt check build clippy test test-doc && assert-git-is-clean
 
 # Run minimal subset of tests to ensure compatibility with MSRV
 ci-test-msrv: env-info test

src/lib.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(not(feature = "cpp"), forbid(unsafe_code))]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
 
@@ -14,6 +15,7 @@ compile_error!("At least one of the features 'cpp' or 'rust' must be enabled");
 pub mod cpp;
 
 #[cfg(feature = "rust")]
+#[forbid(unsafe_code, reason = "Rust code must always be safe")]
 /// Rust re-implementation of `FastPFor` (work in progress)
 pub mod rust;