hashcodecs 0.4.0__tar.gz → 0.6.0__tar.gz

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/.gitignore

@@ -2,8 +2,11 @@
 # will have compiled files and executables
 debug
 target
-dist
-.venv
+fuzz/artifacts
+dist/
+dist-*/
+.venv/
+.venv-*/
 .coverage
 coverage.xml
 

hashcodecs-0.6.0/BENCHMARK.md

@@ -0,0 +1,58 @@
+# Benchmark Details
+
+Environment: Windows 10 x64 and Intel Core Ultra 7 265K.
+
+Conditions: clean builds, one pinned logical CPU, single-threaded execution, and 15 Python samples. The upstream C baseline was compiled explicitly for AVX2, matching the backend selected by hashcodecs on this host. Higher is better.
+
+Python hashcodecs measurements use a CPython 3.12 wheel built against the full C
+API. Unchanged reference series are retained from their latest clean run.
+
+The charts are generated by `uv run python benchmarks/render_charts.py`. Their exact measurements are available in
+[CSV form](docs/benchmarks/results.csv).
+
+## XXH3
+
+The Rust comparison calls xxHash 0.8.3 through `xxhash-c-sys`. Python compares with the upstream `xxhash` extension.
+Batch measurements contain 32 equal-size inputs.
+
+[![Rust XXH3 throughput](docs/benchmarks/xxh3-rust.svg)](docs/benchmarks/xxh3-rust.svg)
+
+[![Python XXH3 throughput](docs/benchmarks/xxh3-python.svg)](docs/benchmarks/xxh3-python.svg)
+
+## Reusable Python Buffers
+
+[![Reusable Python Base64 buffers](docs/benchmarks/base64-python-reusable.svg)](docs/benchmarks/base64-python-reusable.svg)
+
+## Python Memoryview Inputs
+
+Full immutable memoryviews reuse their underlying bytes for inputs of at least 64 KiB.
+
+[![Python Base64 memoryview inputs](docs/benchmarks/base64-python-memoryview.svg)](docs/benchmarks/base64-python-memoryview.svg)
+
+## Python Base64 Batches
+
+The horizontal axis is the batch size and the vertical axis is total input throughput.
+
+[![Python Base64 batch throughput](docs/benchmarks/base64-python-batch.svg)](docs/benchmarks/base64-python-batch.svg)
+
+## Reusable Python Base64 Batch Buffers
+
+These measurements use the `*_batch_into` APIs with one reusable `bytearray` per item.
+
+[![Reusable Python Base64 batch buffers](docs/benchmarks/base64-python-batch-reusable.svg)](docs/benchmarks/base64-python-batch-reusable.svg)
+
+## Large Python Base64 Batches
+
+Each batch item is 1 MiB. The horizontal axis is the batch size.
+
+[![Large Python Base64 batches](docs/benchmarks/base64-python-batch-large.svg)](docs/benchmarks/base64-python-batch-large.svg)
+
+## Mutable Python Inputs
+
+### Base64
+
+[![Mutable Python Base64 inputs](docs/benchmarks/base64-python-mutable.svg)](docs/benchmarks/base64-python-mutable.svg)
+
+### MurmurHash3
+
+[![Mutable Python MurmurHash3 inputs](docs/benchmarks/murmur3-python-mutable.svg)](docs/benchmarks/murmur3-python-mutable.svg)

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/Cargo.lock

@@ -46,9 +46,9 @@ checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
 
 [[package]]
 name = "base64-turbo"
-version = "0.2.0"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "341b5725644ff53e8384ba7c17b9abd9274aa79efc2eb9cf8629cb3cc860d4e3"
+checksum = "8bb14240b770d247c8481cab7c78350daf08b4285885b916632dec270b7e6dfc"
 
 [[package]]
 name = "cast"
@@ -194,17 +194,21 @@ dependencies = [
 
 [[package]]
 name = "hashcodecs"
-version = "0.4.0"
+version = "0.6.0"
 dependencies = [
  "base64",
  "base64-turbo",
  "criterion",
  "fastmurmur3",
+ "memchr",
  "mimalloc",
  "mm3h",
  "murmur3",
  "murmurs",
  "pyo3",
+ "pyo3-build-config",
+ "xxhash-c-sys",
+ "xxhash-rust",
 ]
 
 [[package]]
@@ -575,6 +579,22 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "xxhash-c-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4d4a8210e2c9209f553817636cc6054d3b22424cc879c31b616e4cb4027be705"
+dependencies = [
+ "cc",
+ "libc",
+]
+
+[[package]]
+name = "xxhash-rust"
+version = "0.8.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aee1b19627c7c60102ab80d3a9cbe18de90bfe03bfa6c3715447681f0e8c8af6"
+
 [[package]]
 name = "zerocopy"
 version = "0.8.56"

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "hashcodecs"
-version = "0.4.0"
+version = "0.6.0"
 edition = "2024"
 rust-version = "1.89"
-description = "SIMD-accelerated Base64 codecs and fast MurmurHash3 implementations"
+description = "SIMD-accelerated Base64 codecs and fast MurmurHash3 and xxHash implementations"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/kozistr/hashcodecs-rs"
 publish = false
-keywords = ["base64", "simd", "murmur3", "python"]
+keywords = ["base64", "simd", "murmur3", "xxhash", "python"]
 categories = ["encoding", "algorithms"]
 readme = "README.md"
 
@@ -16,21 +16,27 @@ name = "hashcodecs"
 crate-type = ["rlib", "cdylib"]
 
 [features]
-python = ["dep:pyo3"]
+python = ["dep:memchr", "dep:pyo3"]
 extension-module = ["python", "pyo3/extension-module"]
 
 [dependencies]
+memchr = { version = "2.8.0", optional = true }
 mimalloc = "0.1.52"
-pyo3 = { version = "0.29.2", features = ["abi3-py310"], optional = true }
+pyo3 = { version = "0.29.2", optional = true }
+
+[build-dependencies]
+pyo3-build-config = "0.29.2"
 
 [dev-dependencies]
 base64 = "0.23.1"
-base64-turbo = "0.2.0"
+base64-turbo = "0.3.0"
 criterion = { version = "0.8.2", default-features = false, features = ["cargo_bench_support"] }
 fastmurmur3 = "0.2.0"
 mm3h = "0.1.3"
 murmur3 = "0.5"
 murmurs = "1.0.5"
+xxhash-c-sys = "0.8.7"
+xxhash-rust = { version = "0.8.18", features = ["xxh3"] }
 
 [[bench]]
 name = "base64"
@@ -40,6 +46,15 @@ harness = false
 name = "murmur3"
 harness = false
 
+[[bench]]
+name = "xxhash"
+harness = false
+
+[[test]]
+name = "sanitizers"
+path = "tests/sanitizers.rs"
+harness = false
+
 [profile.release]
 codegen-units = 1
 lto = "fat"

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hashcodecs
-Version: 0.4.0
-Summary: SIMD-accelerated Base64 and MurmurHash3 codecs
+Version: 0.6.0
+Summary: SIMD-accelerated Base64, MurmurHash3, and xxHash codecs
 License-Expression: MIT OR Apache-2.0
 License-File: LICENSE
 License-File: LICENSE-MIT
@@ -21,19 +21,22 @@ Description-Content-Type: text/markdown
 # hashcodecs
 
 [![CI](https://img.shields.io/github/actions/workflow/status/kozistr/hashcodecs-rs/ci.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/kozistr/hashcodecs-rs/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/kozistr/hashcodecs-rs/graph/badge.svg)](https://app.codecov.io/gh/kozistr/hashcodecs-rs)
 [![PyPI](https://img.shields.io/pypi/v/hashcodecs?style=for-the-badge&logo=pypi)](https://pypi.org/project/hashcodecs/)
 [![Python](https://img.shields.io/pypi/pyversions/hashcodecs?style=for-the-badge&logo=python)](https://pypi.org/project/hashcodecs/)
 [![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-brightgreen?style=for-the-badge)](https://github.com/kozistr/hashcodecs-rs#license)
 [![Downloads](https://img.shields.io/pypi/dm/hashcodecs?style=for-the-badge&label=downloads)](https://pypi.org/project/hashcodecs/)
 
-`hashcodecs` provides runtime-dispatched SIMD Base64 codecs and fast, reference-compatible MurmurHash3 functions for Rust and Python.
+`hashcodecs` provides runtime-dispatched SIMD Base64 codecs and fast, reference-compatible MurmurHash3 and XXH3 functions for Rust and Python.
 
 ## Design
 
 - Runtime-dispatched SIMD Base64 with portable scalar fallbacks.
 - Reference-compatible MurmurHash3 with SIMD acceleration.
+- Bit-for-bit compatible XXH3-64 and XXH3-128 with runtime SIMD dispatch and native batch APIs.
 - Rust and Python `*_into` APIs for caller-managed output buffers.
 - A familiar Python Base64 API, including native batch encode and decode operations.
+- Unsafe paths verified with Kani, strict-provenance Miri, ASan/MSan, and differential fuzzing.
 
 ## Install
 
@@ -53,13 +56,14 @@ let mut output = [0_u8; 8];
 let written = hashcodecs::b64encode_into(b"hello", &mut output).unwrap();
 assert_eq!(&output[..written], b"aGVsbG8=");
 assert_eq!(hashcodecs::murmur3_x86_32(b"hello", 0), 0x248b_fa47);
+assert_eq!(hashcodecs::xxh3_64(b"", 0), 0x2d06_8005_38d3_94c2);
 ```
 
 ### Python
 
 ```python
 import hashcodecs.base64 as base64
-from hashcodecs import murmur3_32, murmur3_x64_128
+from hashcodecs import murmur3_32, murmur3_x64_128, xxh3_64, xxh3_128_batch
 
 assert base64.b64encode(b'hello') == b'aGVsbG8='
 assert base64.b64decode(b'aGVsbG8=') == b'hello'
@@ -68,6 +72,11 @@ assert base64.b64decode_batch([b'aGVsbG8=', 'd29ybGQ=']) == [b'hello', b'world']
 assert base64.b64encode(b'hello', padded=False) == b'aGVsbG8'
 assert base64.b64decode(b'aGVsbG8', padded=False, canonical=True) == b'hello'
 assert murmur3_32(b'hello') == 0x248BFA47
+assert xxh3_64(b'') == 0x2D06800538D394C2
+assert xxh3_128_batch([b'hello', b'world']) == [
+    0xB5E9C1AD071B3E7FC779CFAA5E523818,
+    0xFA0D38A9B38280D0891E4985BDB2583E,
+]
 
 payload = b'hello'
 encoded = bytearray(4 * ((len(payload) + 2) // 3))
@@ -101,89 +110,57 @@ Comparison crates are development-only dependencies and are not included in cons
 ```sh
 cargo bench --bench base64
 cargo bench --bench murmur3
+cargo bench --bench xxhash
 uv sync --group benchmark --no-install-project
 uv run --no-project --with . python benchmarks/python_base64.py
 uv run --no-project --with . python benchmarks/python_base64.py --into
 uv run --no-project --with . python benchmarks/python_base64.py --bytearray-input
+uv run --no-project --with . python benchmarks/python_base64.py --memoryview-input
 uv run --no-project --with . python benchmarks/python_base64_batch.py
+uv run --no-project --with . python benchmarks/python_base64_batch.py --large
 uv run --no-project --with . python benchmarks/python_murmur3.py
 uv run --no-project --with . python benchmarks/python_murmur3.py --incremental
+uv run --no-project --with . python benchmarks/python_xxhash.py
 ```
 
+For regression checks that do not need fresh competitor measurements, pass
+`--hashcodecs-only` to any Python benchmark command.
+
+For the same-ISA Windows comparison reported below, rebuild the C baseline with
+`$env:CFLAGS='/O2 /arch:AVX2'; cargo clean -p xxhash-c-sys; cargo bench --bench xxhash`.
+
 ## Base64: Rust
 
-| Alphabet | Input | Operation | hashcodecs | `base64` | `base64-turbo` |
-| --- | --- | --- | ---: | ---: | ---: |
-| Standard | 4 KiB | encode | **20.41 GiB/s** | 5.81 GiB/s | 18.29 GiB/s |
-|  | 4 KiB | decode | **27.11 GiB/s** | 4.33 GiB/s | 16.95 GiB/s |
-|  | 1 MiB | encode | **42.38 GiB/s** | 5.16 GiB/s | 19.60 GiB/s |
-|  | 1 MiB | decode | **31.07 GiB/s** | 4.10 GiB/s | 18.17 GiB/s |
-|  | 32 MiB | encode | **11.97 GiB/s** | 3.28 GiB/s | 10.94 GiB/s |
-|  | 32 MiB | decode | **11.51 GiB/s** | 3.35 GiB/s | 10.45 GiB/s |
-| URL-safe | 4 KiB | encode | **20.46 GiB/s** | 5.81 GiB/s | 18.31 GiB/s |
-|  | 4 KiB | decode | **25.65 GiB/s** | 4.35 GiB/s | 16.96 GiB/s |
-|  | 1 MiB | encode | **42.56 GiB/s** | 5.18 GiB/s | 19.66 GiB/s |
-|  | 1 MiB | decode | **29.42 GiB/s** | 4.08 GiB/s | 18.16 GiB/s |
-|  | 32 MiB | encode | **11.86 GiB/s** | 3.29 GiB/s | 11.09 GiB/s |
-|  | 32 MiB | decode | **11.67 GiB/s** | 3.36 GiB/s | 10.62 GiB/s |
+[![Rust Base64 throughput](docs/benchmarks/base64-rust.svg)](docs/benchmarks/base64-rust.svg)
 
 ## MurmurHash3: Rust
 
-| Variant | Input | hashcodecs | `murmur3` | `murmurs` | `fastmurmur3` | `mm3h` |
-| --- | --- | ---: | ---: | ---: | ---: | ---: |
-| x86 32-bit | 4 KiB | **4.30 GiB/s** | 2.60 GiB/s | 4.09 GiB/s | n/a | **4.30 GiB/s** |
-|  | 1 MiB | **4.26 GiB/s** | 2.59 GiB/s | 4.04 GiB/s | n/a | 4.25 GiB/s |
-|  | 32 MiB | **4.21 GiB/s** | 2.54 GiB/s | 3.87 GiB/s | n/a | 4.03 GiB/s |
-| x86 128-bit | 4 KiB | **9.54 GiB/s** | 4.97 GiB/s | 8.64 GiB/s | n/a | n/a |
-|  | 1 MiB | **9.84 GiB/s** | 5.06 GiB/s | 8.77 GiB/s | n/a | n/a |
-|  | 32 MiB | **9.63 GiB/s** | 4.84 GiB/s | 6.05 GiB/s | n/a | n/a |
-| x64 128-bit | 4 KiB | **10.76 GiB/s** | 6.83 GiB/s | 9.45 GiB/s | 10.06 GiB/s | 9.54 GiB/s |
-|  | 1 MiB | **10.84 GiB/s** | 6.89 GiB/s | 9.51 GiB/s | 10.04 GiB/s | 9.51 GiB/s |
-|  | 32 MiB | **10.12 GiB/s** | 6.11 GiB/s | 6.64 GiB/s | 7.25 GiB/s | 6.70 GiB/s |
+[![Rust MurmurHash3 throughput](docs/benchmarks/murmur3-rust.svg)](docs/benchmarks/murmur3-rust.svg)
+
+## XXH3: Rust
+
+`upstream C` is xxHash 0.8.3 built through `xxhash-c-sys` with AVX2 enabled, matching the backend selected by hashcodecs on the benchmark host. Batch results hash 32 equal-size inputs and include result-vector allocation.
+
+[![Rust XXH3 throughput](docs/benchmarks/xxh3-rust.svg)](docs/benchmarks/xxh3-rust.svg)
 
 ## Base64: Python
 
 Python decoding uses `validate=True`, and `hashcodecs` passes `bytes` directly into Rust without an input copy.
 
-| Alphabet | Input | Operation | hashcodecs | CPython `base64` | `pybase64` |
-| --- | --- | --- | ---: | ---: | ---: |
-| Standard | 4 KiB | encode | 13.57 GiB/s | 0.48 GiB/s | **14.06 GiB/s** |
-|  | 4 KiB | decode | **16.70 GiB/s** | 1.13 GiB/s | 8.47 GiB/s |
-|  | 1 MiB | encode | **3.28 GiB/s** | 0.44 GiB/s | 3.02 GiB/s |
-|  | 1 MiB | decode | **4.02 GiB/s** | 0.95 GiB/s | 3.68 GiB/s |
-|  | 32 MiB | encode | **2.92 GiB/s** | 0.43 GiB/s | 2.84 GiB/s |
-|  | 32 MiB | decode | 3.40 GiB/s | 0.94 GiB/s | **3.69 GiB/s** |
-| URL-safe | 4 KiB | encode | **12.63 GiB/s** | 0.41 GiB/s | 1.19 GiB/s |
-|  | 4 KiB | decode | **11.34 GiB/s** | 0.76 GiB/s | 1.56 GiB/s |
-|  | 1 MiB | encode | **3.24 GiB/s** | 0.36 GiB/s | 0.91 GiB/s |
-|  | 1 MiB | decode | **4.15 GiB/s** | 0.63 GiB/s | 1.45 GiB/s |
-|  | 32 MiB | encode | **3.03 GiB/s** | 0.36 GiB/s | 0.90 GiB/s |
-|  | 32 MiB | decode | **3.40 GiB/s** | 0.61 GiB/s | 1.48 GiB/s |
+[![Python Base64 throughput](docs/benchmarks/base64-python.svg)](docs/benchmarks/base64-python.svg)
 
 ## MurmurHash3: Python
 
-| Variant | API | Input | hashcodecs | `mmh3` |
-| --- | --- | --- | ---: | ---: |
-| x86 32-bit | one-shot | 4 KiB | **3.79 GiB/s** | 3.71 GiB/s |
-|  |  | 1 MiB | **3.98 GiB/s** | 3.83 GiB/s |
-|  |  | 32 MiB | **3.97 GiB/s** | 3.66 GiB/s |
-|  | incremental | 4 KiB | **3.58 GiB/s** | **3.58 GiB/s** |
-|  |  | 1 MiB | **3.96 GiB/s** | 3.81 GiB/s |
-|  |  | 32 MiB | **3.92 GiB/s** | 3.74 GiB/s |
-| x86 128-bit | one-shot | 4 KiB | 8.09 GiB/s | **8.21 GiB/s** |
-|  |  | 1 MiB | **9.22 GiB/s** | 8.87 GiB/s |
-|  |  | 32 MiB | **9.12 GiB/s** | 6.15 GiB/s |
-|  | incremental | 4 KiB | **7.02 GiB/s** | 0.77 GiB/s |
-|  |  | 1 MiB | **9.17 GiB/s** | 0.80 GiB/s |
-|  |  | 32 MiB | **9.01 GiB/s** | 0.79 GiB/s |
-| x64 128-bit | one-shot | 4 KiB | 8.68 GiB/s | **9.46 GiB/s** |
-|  |  | 1 MiB | 10.10 GiB/s | **10.24 GiB/s** |
-|  |  | 32 MiB | **9.54 GiB/s** | 6.61 GiB/s |
-|  | incremental | 4 KiB | 7.70 GiB/s | **7.99 GiB/s** |
-|  |  | 1 MiB | **10.01 GiB/s** | 9.28 GiB/s |
-|  |  | 32 MiB | **9.41 GiB/s** | 7.34 GiB/s |
-
-Reusable-buffer and mutable-input results are available in [BENCHMARK.md](https://github.com/kozistr/hashcodecs-rs/blob/main/BENCHMARK.md).
+[![Python MurmurHash3 throughput](docs/benchmarks/murmur3-python.svg)](docs/benchmarks/murmur3-python.svg)
+
+## XXH3: Python
+
+The batch comparison uses one native `hashcodecs` call versus a loop over the upstream `xxhash` extension.
+
+[![Python XXH3 throughput](docs/benchmarks/xxh3-python.svg)](docs/benchmarks/xxh3-python.svg)
+
+Reusable-buffer and mutable-input charts are available in [BENCHMARK.md](BENCHMARK.md). Exact chart values are
+available as [CSV](docs/benchmarks/results.csv).
 
 ## SIMD References
 

hashcodecs-0.6.0/README.md

@@ -0,0 +1,147 @@
+# hashcodecs
+
+[![CI](https://img.shields.io/github/actions/workflow/status/kozistr/hashcodecs-rs/ci.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/kozistr/hashcodecs-rs/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/kozistr/hashcodecs-rs/graph/badge.svg)](https://app.codecov.io/gh/kozistr/hashcodecs-rs)
+[![PyPI](https://img.shields.io/pypi/v/hashcodecs?style=for-the-badge&logo=pypi)](https://pypi.org/project/hashcodecs/)
+[![Python](https://img.shields.io/pypi/pyversions/hashcodecs?style=for-the-badge&logo=python)](https://pypi.org/project/hashcodecs/)
+[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-brightgreen?style=for-the-badge)](https://github.com/kozistr/hashcodecs-rs#license)
+[![Downloads](https://img.shields.io/pypi/dm/hashcodecs?style=for-the-badge&label=downloads)](https://pypi.org/project/hashcodecs/)
+
+`hashcodecs` provides runtime-dispatched SIMD Base64 codecs and fast, reference-compatible MurmurHash3 and XXH3 functions for Rust and Python.
+
+## Design
+
+- Runtime-dispatched SIMD Base64 with portable scalar fallbacks.
+- Reference-compatible MurmurHash3 with SIMD acceleration.
+- Bit-for-bit compatible XXH3-64 and XXH3-128 with runtime SIMD dispatch and native batch APIs.
+- Rust and Python `*_into` APIs for caller-managed output buffers.
+- A familiar Python Base64 API, including native batch encode and decode operations.
+- Unsafe paths verified with Kani, strict-provenance Miri, ASan/MSan, and differential fuzzing.
+
+## Install
+
+```
+pip3 install hashcodecs
+```
+
+## Usage
+
+### Rust
+
+```rust
+let encoded = hashcodecs::b64encode(b"hello");
+assert_eq!(encoded, "aGVsbG8=");
+
+let mut output = [0_u8; 8];
+let written = hashcodecs::b64encode_into(b"hello", &mut output).unwrap();
+assert_eq!(&output[..written], b"aGVsbG8=");
+assert_eq!(hashcodecs::murmur3_x86_32(b"hello", 0), 0x248b_fa47);
+assert_eq!(hashcodecs::xxh3_64(b"", 0), 0x2d06_8005_38d3_94c2);
+```
+
+### Python
+
+```python
+import hashcodecs.base64 as base64
+from hashcodecs import murmur3_32, murmur3_x64_128, xxh3_64, xxh3_128_batch
+
+assert base64.b64encode(b'hello') == b'aGVsbG8='
+assert base64.b64decode(b'aGVsbG8=') == b'hello'
+assert base64.b64encode_batch([b'hello', b'world']) == [b'aGVsbG8=', b'd29ybGQ=']
+assert base64.b64decode_batch([b'aGVsbG8=', 'd29ybGQ=']) == [b'hello', b'world']
+assert base64.b64encode(b'hello', padded=False) == b'aGVsbG8'
+assert base64.b64decode(b'aGVsbG8', padded=False, canonical=True) == b'hello'
+assert murmur3_32(b'hello') == 0x248BFA47
+assert xxh3_64(b'') == 0x2D06800538D394C2
+assert xxh3_128_batch([b'hello', b'world']) == [
+    0xB5E9C1AD071B3E7FC779CFAA5E523818,
+    0xFA0D38A9B38280D0891E4985BDB2583E,
+]
+
+payload = b'hello'
+encoded = bytearray(4 * ((len(payload) + 2) // 3))
+encoded_len = base64.b64encode_into(payload, encoded)
+decoded = bytearray(len(encoded))
+decoded_len = base64.b64decode_into(encoded, decoded, validate=True)
+assert encoded[:encoded_len] == b'aGVsbG8='
+assert decoded[:decoded_len] == payload
+
+hasher = murmur3_x64_128(seed=42)
+hasher.update(b'hello')
+assert hasher.hexdigest() == hasher.digest().hex()
+```
+
+Build an installable wheel and source distribution with:
+
+```sh
+uv build
+```
+
+# Benchmark
+
+Environment: Windows 10 x64 and Intel Core Ultra 7 265K.
+
+Conditions: clean builds, one pinned logical CPU, single-threaded execution, 50 Rust samples, and 15 Python samples. Returned-output allocation is included except in the reusable-buffer table. Higher is better.
+
+## Run Locally
+
+Comparison crates are development-only dependencies and are not included in consumer builds.
+
+```sh
+cargo bench --bench base64
+cargo bench --bench murmur3
+cargo bench --bench xxhash
+uv sync --group benchmark --no-install-project
+uv run --no-project --with . python benchmarks/python_base64.py
+uv run --no-project --with . python benchmarks/python_base64.py --into
+uv run --no-project --with . python benchmarks/python_base64.py --bytearray-input
+uv run --no-project --with . python benchmarks/python_base64.py --memoryview-input
+uv run --no-project --with . python benchmarks/python_base64_batch.py
+uv run --no-project --with . python benchmarks/python_base64_batch.py --large
+uv run --no-project --with . python benchmarks/python_murmur3.py
+uv run --no-project --with . python benchmarks/python_murmur3.py --incremental
+uv run --no-project --with . python benchmarks/python_xxhash.py
+```
+
+For regression checks that do not need fresh competitor measurements, pass
+`--hashcodecs-only` to any Python benchmark command.
+
+For the same-ISA Windows comparison reported below, rebuild the C baseline with
+`$env:CFLAGS='/O2 /arch:AVX2'; cargo clean -p xxhash-c-sys; cargo bench --bench xxhash`.
+
+## Base64: Rust
+
+[![Rust Base64 throughput](docs/benchmarks/base64-rust.svg)](docs/benchmarks/base64-rust.svg)
+
+## MurmurHash3: Rust
+
+[![Rust MurmurHash3 throughput](docs/benchmarks/murmur3-rust.svg)](docs/benchmarks/murmur3-rust.svg)
+
+## XXH3: Rust
+
+`upstream C` is xxHash 0.8.3 built through `xxhash-c-sys` with AVX2 enabled, matching the backend selected by hashcodecs on the benchmark host. Batch results hash 32 equal-size inputs and include result-vector allocation.
+
+[![Rust XXH3 throughput](docs/benchmarks/xxh3-rust.svg)](docs/benchmarks/xxh3-rust.svg)
+
+## Base64: Python
+
+Python decoding uses `validate=True`, and `hashcodecs` passes `bytes` directly into Rust without an input copy.
+
+[![Python Base64 throughput](docs/benchmarks/base64-python.svg)](docs/benchmarks/base64-python.svg)
+
+## MurmurHash3: Python
+
+[![Python MurmurHash3 throughput](docs/benchmarks/murmur3-python.svg)](docs/benchmarks/murmur3-python.svg)
+
+## XXH3: Python
+
+The batch comparison uses one native `hashcodecs` call versus a loop over the upstream `xxhash` extension.
+
+[![Python XXH3 throughput](docs/benchmarks/xxh3-python.svg)](docs/benchmarks/xxh3-python.svg)
+
+Reusable-buffer and mutable-input charts are available in [BENCHMARK.md](BENCHMARK.md). Exact chart values are
+available as [CSV](docs/benchmarks/results.csv).
+
+## SIMD References
+
+The SIMD implementation follows the approach described in [Faster Base64 Encoding and Decoding using AVX2 Instructions](https://arxiv.org/abs/1704.00605), with AVX-512 VBMI and AArch64 NEON backends selected automatically when available.

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/benches/base64.rs

@@ -6,7 +6,7 @@ use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_m
 
 mod support;
 
-const SIZES: [usize; 3] = [4 * 1024, 1024 * 1024, 32 * 1024 * 1024];
+const SIZES: [usize; 4] = [1024, 4 * 1024, 1024 * 1024, 8 * 1024 * 1024];
 const SAMPLE_SIZE: usize = 50;
 
 fn data(size: usize) -> Vec<u8> {

{hashcodecs-0.4.0 → hashcodecs-0.6.0}/benches/murmur3.rs

@@ -6,7 +6,7 @@ use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_m
 
 mod support;
 
-const SIZES: [usize; 3] = [4 * 1024, 1024 * 1024, 32 * 1024 * 1024];
+const SIZES: [usize; 4] = [1024, 4 * 1024, 1024 * 1024, 8 * 1024 * 1024];
 const SAMPLE_SIZE: usize = 50;
 
 fn data(size: usize) -> Vec<u8> {

hashcodecs-0.6.0/benches/xxhash.rs

@@ -0,0 +1,119 @@
+use std::ffi::c_void;
+use std::hint::black_box;
+use std::time::Duration;
+
+use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
+
+mod support;
+
+const SIZES: [usize; 5] = [64, 1024, 4 * 1024, 1024 * 1024, 8 * 1024 * 1024];
+
+fn data(size: usize, salt: u8) -> Vec<u8> {
+    (0..size)
+        .map(|index| (index as u8).wrapping_mul(31).wrapping_add(salt))
+        .collect()
+}
+
+fn c_xxh3_64(input: &[u8], seed: u64) -> u64 {
+    unsafe {
+        xxhash_c_sys::XXH3_64bits_withSeed(input.as_ptr().cast::<c_void>(), input.len(), seed)
+    }
+}
+
+fn c_xxh3_128(input: &[u8], seed: u64) -> [u64; 2] {
+    let hash = unsafe {
+        xxhash_c_sys::XXH3_128bits_withSeed(input.as_ptr().cast::<c_void>(), input.len(), seed)
+    };
+    [hash.low64, hash.high64]
+}
+
+fn one_shot(c: &mut Criterion) {
+    for size in SIZES {
+        let input = data(size, 17);
+        let mut group = c.benchmark_group(format!("xxh3_64/{size}"));
+        group.throughput(Throughput::Bytes(size as u64));
+        assert_eq!(hashcodecs::xxh3_64(&input, 42), c_xxh3_64(&input, 42));
+        group.bench_function("hashcodecs", |bench| {
+            bench.iter(|| hashcodecs::xxh3_64(black_box(&input), 42))
+        });
+        group.bench_function("upstream_c", |bench| {
+            bench.iter(|| c_xxh3_64(black_box(&input), 42))
+        });
+        group.finish();
+
+        let mut group = c.benchmark_group(format!("xxh3_128/{size}"));
+        group.throughput(Throughput::Bytes(size as u64));
+        assert_eq!(hashcodecs::xxh3_128(&input, 42), c_xxh3_128(&input, 42));
+        group.bench_function("hashcodecs", |bench| {
+            bench.iter(|| hashcodecs::xxh3_128(black_box(&input), 42))
+        });
+        group.bench_function("upstream_c", |bench| {
+            bench.iter(|| c_xxh3_128(black_box(&input), 42))
+        });
+        group.finish();
+    }
+}
+
+fn batch(c: &mut Criterion) {
+    const ITEMS: usize = 32;
+    for size in [64, 1024, 4 * 1024, 1024 * 1024] {
+        let owned = (0..ITEMS)
+            .map(|index| data(size, index as u8))
+            .collect::<Vec<_>>();
+        let inputs = owned.iter().map(Vec::as_slice).collect::<Vec<_>>();
+        let mut group = c.benchmark_group(format!("xxh3_batch/{size}"));
+        group.throughput(Throughput::Bytes((size * ITEMS) as u64));
+
+        group.bench_with_input(
+            BenchmarkId::new("hashcodecs_64", ITEMS),
+            &inputs,
+            |bench, inputs| bench.iter(|| hashcodecs::xxh3_64_batch(black_box(inputs), 42)),
+        );
+        group.bench_with_input(
+            BenchmarkId::new("upstream_c_64", ITEMS),
+            &inputs,
+            |bench, inputs| {
+                bench.iter(|| {
+                    inputs
+                        .iter()
+                        .map(|input| c_xxh3_64(black_box(input), 42))
+                        .collect::<Vec<_>>()
+                })
+            },
+        );
+        group.bench_with_input(
+            BenchmarkId::new("hashcodecs_128", ITEMS),
+            &inputs,
+            |bench, inputs| bench.iter(|| hashcodecs::xxh3_128_batch(black_box(inputs), 42)),
+        );
+        group.bench_with_input(
+            BenchmarkId::new("upstream_c_128", ITEMS),
+            &inputs,
+            |bench, inputs| {
+                bench.iter(|| {
+                    inputs
+                        .iter()
+                        .map(|input| c_xxh3_128(black_box(input), 42))
+                        .collect::<Vec<_>>()
+                })
+            },
+        );
+        group.finish();
+    }
+}
+
+fn xxhash(c: &mut Criterion) {
+    support::pin_to_one_cpu();
+    one_shot(c);
+    batch(c);
+}
+
+criterion_group! {
+    name = benches;
+    config = Criterion::default()
+        .measurement_time(Duration::from_secs(1))
+        .sample_size(30)
+        .warm_up_time(Duration::from_millis(300));
+    targets = xxhash
+}
+criterion_main!(benches);