hashcodecs 1.0.0__tar.gz → 1.2.0__tar.gz

hashcodecs-1.2.0/BENCHMARK.md

@@ -0,0 +1,120 @@
+# Benchmark Details
+
+Run the suite on Windows 10 x64 with an Intel Core Ultra 7 265K.
+
+Pin one logical CPU. Run each case in one thread. Collect 50 Rust samples and 15 Python samples. Compile the C
+baseline with AVX2, the backend that hashcodecs selects on this host. Higher throughput wins.
+
+Build the Python wheel with CPython 3.12 and the full C API. Keep competitor values from the latest comparison run.
+Use `uv run python benchmarks/render_charts.py` to render the charts. Read exact values in
+[docs/benchmarks/results.csv](docs/benchmarks/results.csv).
+
+## Timing Controls
+
+Every Python benchmark accepts `--samples` (default: 15) and `--minimum-sample-seconds` (default: 0.2). Their
+sampling time per case is at least their product, plus calibration; use lower values only for exploratory runs. For a quicker full
+hashcodecs-only pass, use `--hashcodecs-only --samples 3 --minimum-sample-seconds 0.05` with each Python benchmark
+script.
+
+## Python Call Costs
+
+Run `python benchmarks/python_calls.py` to measure positional calls from 0 through 256 bytes in nanoseconds per
+call. Use `--keywords` for positional and keyword calls at 64 bytes, or `--thresholds` for latency around the
+GIL-detachment cutoffs. The `--thread-scaling` mode measures aggregate throughput with one, two, and four threads;
+it does not pin the process to one logical CPU.
+
+## XXH3
+
+For the Rust comparison, link hashcodecs with xxHash 0.8.3 through `xxhash-c-sys`. Build the C baseline with AVX2.
+For Python, run the upstream `xxhash` extension beside hashcodecs. Pass 32 equal-size inputs to each batch case.
+The Rust remainder cases pass two or three equal-size long inputs. Run Python remainder cases with
+`python benchmarks/python_xxhash.py --batch-counts 2 3`.
+
+Use the focused one-shot run to cover the AVX2 four-chain boundaries:
+
+```sh
+cargo bench --bench xxhash -- --sample-size 50 "xxh3_(64|128)/(241|512|768|1024|1536|2048|4096)/hashcodecs"
+```
+
+[![Rust XXH3 throughput](docs/benchmarks/xxh3-rust.svg)](docs/benchmarks/xxh3-rust.svg)
+
+[![Rust XXH3 batch remainder throughput](docs/benchmarks/xxh3-rust-batch-remainders.svg)](docs/benchmarks/xxh3-rust-batch-remainders.svg)
+
+[![Python XXH3 throughput](docs/benchmarks/xxh3-python.svg)](docs/benchmarks/xxh3-python.svg)
+
+## Reusable Python Buffers
+
+Pass one reusable `bytearray` to each `*_into` call.
+
+[![Reusable Python Base64 buffers](docs/benchmarks/base64-python-reusable.svg)](docs/benchmarks/base64-python-reusable.svg)
+
+## Lenient Python Base64
+
+Run `python benchmarks/python_base64.py --lenient`. The MIME cases insert CRLF after each 76-character line. The
+noisy cases insert `!` at the same boundaries. Both cases measure returned bytes and reusable output buffers.
+
+[![Lenient Python Base64 throughput](docs/benchmarks/base64-python-lenient.svg)](docs/benchmarks/base64-python-lenient.svg)
+
+## Python Memoryview Inputs
+
+Use `--memoryview-input` for full immutable views and `--sliced-memoryview-input` for equal-length views with a
+nonzero starting offset. The latter covers the copy/stabilization path used by slices while keeping the encoded data
+identical.
+
+[![Python Base64 memoryview inputs](docs/benchmarks/base64-python-memoryview.svg)](docs/benchmarks/base64-python-memoryview.svg)
+
+## Python Base64 Batches
+
+Set the horizontal axis to batch size. Read total input throughput on the vertical axis.
+
+[![Python Base64 batch throughput](docs/benchmarks/base64-python-batch.svg)](docs/benchmarks/base64-python-batch.svg)
+
+For focused runs, override the item and batch sizes directly. `--decode-only` avoids carrying encode allocator state
+into a decode investigation:
+
+```sh
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 512 768 1024 1280 2048 --decode-only
+```
+
+Use a single operation when recording a sampling profile, or compare traced allocations without a sampler:
+
+```sh
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 1024 --profile-operation returned
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 1024 --allocation-profile
+```
+
+Add `--profile-direction encode` for returned encoding. By default, the profiling loop assigns the next result
+before releasing the previous one. Add `--discard-profile-result` to release each result before the next call. Use
+`b64encode_batch_into` for that workload.
+
+```sh
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 1024 --profile-direction encode --profile-operation returned
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 1024 --profile-direction encode --profile-operation returned --discard-profile-result
+python benchmarks/python_base64_batch.py --item-sizes 4096 --batch-sizes 1024 --profile-direction encode --allocation-profile
+```
+
+## Reusable Python Base64 Batch Buffers
+
+Pass one reusable `bytearray` to each item in the batch. Use the `*_batch_into` APIs.
+
+[![Reusable Python Base64 batch buffers](docs/benchmarks/base64-python-batch-reusable.svg)](docs/benchmarks/base64-python-batch-reusable.svg)
+
+## Large Python Base64 Batches
+
+Use 1 MiB for each batch item. Set the horizontal axis to batch size.
+
+[![Large Python Base64 batches](docs/benchmarks/base64-python-batch-large.svg)](docs/benchmarks/base64-python-batch-large.svg)
+
+## Mutable Python Inputs
+
+### Base64
+
+Pass `bytearray` inputs to the Base64 API.
+
+[![Mutable Python Base64 inputs](docs/benchmarks/base64-python-mutable.svg)](docs/benchmarks/base64-python-mutable.svg)
+
+### MurmurHash3
+
+Pass `bytearray` inputs to the MurmurHash3 API.
+
+[![Mutable Python MurmurHash3 inputs](docs/benchmarks/murmur3-python-mutable.svg)](docs/benchmarks/murmur3-python-mutable.svg)

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/CHANGELOG.md

@@ -4,6 +4,34 @@ This file records notable user-facing changes to `hashcodecs`. Version 1.0.0 sta
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-08-25
+
+### What's Changed
+* fix: harden free-threaded bindings and API correctness by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/47
+* feat: accelerate Python batch outputs by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/48
+* feat: add native lenient Base64 decoding by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/49
+* update: tune Python detach thresholds by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/50
+* fix: harden Base64 binding edge cases by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/51
+* fix: stabilize Base64 GIL release test by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/52
+* feat: accelerate XXH3 batch remainders by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/53
+* perf: refresh Base64 batch benchmarks by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/54
+* perf: accelerate XXH3 long inputs by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/55
+* perf: profile Base64 batch allocations by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/56
+* refactor: organize Python binding infrastructure by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/57
+
+
+**Full Changelog**: https://github.com/kozistr/hashcodecs-rs/compare/v1.1.0...v1.2.0
+
+## [1.1.0] - 2026-08-23
+
+### What's Changed
+* chore: use trusted publishing for crates.io by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/44
+* refactor: establish clean architecture boundaries by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/45
+* feat: borrow contiguous Python buffers by @kozistr in https://github.com/kozistr/hashcodecs-rs/pull/46
+
+
+**Full Changelog**: https://github.com/kozistr/hashcodecs-rs/compare/v1.0.0...v1.1.0
+
 ## [1.0.0] - 2026-08-22
 
 ### What's Changed
@@ -89,7 +117,9 @@ This file records notable user-facing changes to `hashcodecs`. Version 1.0.0 sta
 - Initial Python and Rust APIs for Base64 and MurmurHash3.
 - Runtime SIMD dispatch and platform-specific CPython wheels.
 
-[Unreleased]: https://github.com/kozistr/hashcodecs-rs/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/kozistr/hashcodecs-rs/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/kozistr/hashcodecs-rs/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/kozistr/hashcodecs-rs/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/kozistr/hashcodecs-rs/compare/v0.6.1...v1.0.0
 [0.6.1]: https://github.com/kozistr/hashcodecs-rs/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/kozistr/hashcodecs-rs/compare/v0.5.0...v0.6.0

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/CITATION.cff

@@ -5,8 +5,8 @@ authors:
     given-names: Hyeongchan
     orcid: https://orcid.org/0000-0002-1729-0580
 title: "hashcodecs: SIMD-accelerated Base64, MurmurHash3, and XXH3 for Python and Rust"
-version: 1.0.0
-date-released: 2026-08-22
+version: 1.2.0
+date-released: 2026-08-25
 license: "MIT OR Apache-2.0"
 repository-code: "https://github.com/kozistr/hashcodecs-rs"
 url: "https://github.com/kozistr/hashcodecs-rs"

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/Cargo.lock

@@ -194,7 +194,7 @@ dependencies = [
 
 [[package]]
 name = "hashcodecs"
-version = "1.0.0"
+version = "1.2.0"
 dependencies = [
  "base64",
  "base64-turbo",

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hashcodecs"
-version = "1.0.0"
+version = "1.2.0"
 edition = "2024"
 rust-version = "1.89"
 description = "SIMD-accelerated Base64 codecs and fast MurmurHash3 and xxHash implementations"

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hashcodecs
-Version: 1.0.0
+Version: 1.2.0
 Summary: SIMD-accelerated Base64, MurmurHash3, and xxHash codecs
 Project-URL: Documentation, https://hashcodecs-rs.readthedocs.io/
 Project-URL: Repository, https://github.com/kozistr/hashcodecs-rs
@@ -41,24 +41,26 @@ Description-Content-Type: text/markdown
 ![Total Downloads](https://img.shields.io/pepy/dt/hashcodecs?style=for-the-badge&label=Total%20Downloads)
 ![Monthly Downloads](https://img.shields.io/pypi/dm/hashcodecs?style=for-the-badge&label=Monthly%20downloads)
 
+<p align="center">
+  <a href="BENCHMARK.md">
+    <img src="docs/benchmarks/performance-at-a-glance.svg" alt="CPython 3.12 URL-safe Base64 encoding and decoding benchmark">
+  </a>
+</p>
+
 SIMD-accelerated Base64, MurmurHash3, and XXH3 for Python and Rust.
 
 Move byte-heavy work into Rust without changing your Python inputs. `hashcodecs` accepts `bytes`, `bytearray`, and
 `memoryview`, selects the best available SIMD backend, and exposes batch and reusable-buffer APIs.
 
 ## Features
+
 - Base64 encode and decode with standard, URL-safe, padded, unpadded, wrapped, and canonical modes.
 - MurmurHash3 x86-32, x86-128, and x64-128 with one-shot and incremental APIs.
 - Bit-for-bit compatible XXH3-64 and XXH3-128 with one-shot and native batch APIs.
 - Caller-managed `*_into` outputs for allocation-sensitive workloads.
 - Runtime dispatch across AVX-512, AVX2, SSE4.1, SSSE3, NEON, and scalar implementations where applicable.
 - Direct CPython buffer handling for `bytes`, `bytearray`, and `memoryview` inputs.
-- Install wheels for CPython 3.10 through 3.15 and free-threaded CPython
-  3.14t and 3.15t on Linux, macOS, and Windows.
-
-## Citation
-
-If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).
+- Install wheels for CPython 3.10 through 3.15 and free-threaded CPython 3.14t and 3.15t on Linux, macOS, and Windows.
 
 ## Installation
 
@@ -66,21 +68,6 @@ If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).
 pip3 install hashcodecs
 ```
 
-## Compatibility
-
-Version 1.x keeps the documented Python API stable under the
-[compatibility policy](docs/compatibility.md). Release wheels target CPython 3.10 through 3.15 on manylinux x86-64,
-macOS 11+ ARM64, and Windows x86-64. CPython 3.14t and 3.15t receive free-threaded wheels on the same platforms.
-
-The Rust crate and Python package share one release version. Before 1.0, minor releases may contain breaking Rust API
-changes; the documented Python API follows the compatibility policy below.
-See [Security Policy](SECURITY.md) for vulnerability reporting.
-
-## Performance snapshot
-
-On the benchmark host, `hashcodecs.xxh3_64` processes a 1 MiB input at 78.83 GiB/s. The operator pinned one logical
-CPU and measured hashcodecs alone. At 256 B items in batches of 64, the Base64 batch API reaches 8.56 GiB/s for encode and 7.60 GiB/s for decode. The per-item loop reaches 4.41 and 3.39 GiB/s. Read the [benchmark details](BENCHMARK.md) and [raw results](docs/benchmarks/results.csv).
-
 ## Python
 
 The Base64 module follows familiar Python conventions while adding explicit padding, canonical validation, batch,
@@ -163,10 +150,14 @@ assert_eq!(
 
 ## Architecture
 
-The Rust core owns algorithm behavior and SIMD dispatch. A thin CPython layer handles argument parsing, buffer
+The Rust core owns algorithm behavior and SIMD dispatch. A substantial CPython layer handles argument parsing, buffer
 ownership, reusable outputs, and GIL decisions; root-level Python modules provide typed public exports without
 adding per-call wrappers.
 
+Each Rust algorithm exposes a small public façade. Base64 groups internals by encode and decode operation and
+places ISA kernels such as `encode/avx2.rs` and `decode/ssse3.rs` under their operation. MurmurHash3 groups code by
+canonical variant. XXH3 uses processing-stage modules, with long-input ISA kernels under `xxhash/long/`.
+
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the module layout, dispatch model, algorithm data flows,
 CPython boundary, and safety invariants.
 
@@ -222,12 +213,14 @@ 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_batch.py
+uv run --no-project --with . python benchmarks/python_calls.py
 uv run --no-project --with . python benchmarks/python_murmur3.py
 uv run --no-project --with . python benchmarks/python_xxhash.py
 ```
 
-The Python benchmarks expose focused modes such as `--into`, `--bytearray-input`, `--memoryview-input`,
-`--incremental`, `--large`, and `--hashcodecs-only`. Use `--help` on a benchmark script for its supported modes.
+The Python benchmarks expose focused modes such as `--into`, `--lenient`, `--bytearray-input`, `--memoryview-input`,
+`--sliced-memoryview-input`, `--incremental`, `--large`, and `--hashcodecs-only`. All scripts also accept `--samples` and
+`--minimum-sample-seconds`; use `--help` on a benchmark script for its supported modes and defaults.
 
 For the same-ISA Windows XXH3 comparison shown above, rebuild the C baseline with:
 
@@ -237,6 +230,13 @@ cargo clean -p xxhash-c-sys
 cargo bench --bench xxhash
 ```
 
+## Performance snapshot
+
+In the full 2026-08-23 hashcodecs-only run on the benchmark host, `hashcodecs.xxh3_64` processes a 1 MiB input at
+79.20 GiB/s. With 256 B items in batches of 64, the Base64 batch API reaches 8.80 GiB/s for encode and 7.58 GiB/s for
+decode. The run pins one logical CPU and uses 15 samples with a 0.2-second minimum per sample. Read the
+[benchmark details](BENCHMARK.md) and [raw comparison results](docs/benchmarks/results.csv).
+
 ## Development
 
 Build the Python wheel and source distribution:
@@ -259,15 +259,21 @@ uv run --frozen --no-sync pytest tests --cov=hashcodecs --cov-branch --cov-fail-
 Optimized paths are also checked with differential fuzzing, Kani, strict-provenance Miri, AddressSanitizer, and
 MemorySanitizer in CI.
 
+## Compatibility
+
+Version 1.x keeps the documented Python API stable under the
+[compatibility policy](docs/compatibility.md). Release wheels target CPython 3.10 through 3.15 on manylinux x86-64,
+macOS 11+ ARM64, and Windows x86-64. CPython 3.14t and 3.15t receive free-threaded wheels on the same platforms.
+
+The Rust crate and Python package share one release version. The documented Python API follows the compatibility
+policy below. See [Security Policy](SECURITY.md) for vulnerability reporting.
+
 ## References
 
 The Base64 SIMD implementation follows the approach described in
 [Faster Base64 Encoding and Decoding using AVX2 Instructions](https://arxiv.org/abs/1704.00605), extended with
 runtime-selected AVX-512 VBMI and AArch64 NEON backends.
 
-## License
-
-Licensed under either of the following, at your option:
+## Citation
 
-- [Apache License 2.0](LICENSE)
-- [MIT License](LICENSE-MIT)
+If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/README.md

@@ -10,24 +10,26 @@
 ![Total Downloads](https://img.shields.io/pepy/dt/hashcodecs?style=for-the-badge&label=Total%20Downloads)
 ![Monthly Downloads](https://img.shields.io/pypi/dm/hashcodecs?style=for-the-badge&label=Monthly%20downloads)
 
+<p align="center">
+  <a href="BENCHMARK.md">
+    <img src="docs/benchmarks/performance-at-a-glance.svg" alt="CPython 3.12 URL-safe Base64 encoding and decoding benchmark">
+  </a>
+</p>
+
 SIMD-accelerated Base64, MurmurHash3, and XXH3 for Python and Rust.
 
 Move byte-heavy work into Rust without changing your Python inputs. `hashcodecs` accepts `bytes`, `bytearray`, and
 `memoryview`, selects the best available SIMD backend, and exposes batch and reusable-buffer APIs.
 
 ## Features
+
 - Base64 encode and decode with standard, URL-safe, padded, unpadded, wrapped, and canonical modes.
 - MurmurHash3 x86-32, x86-128, and x64-128 with one-shot and incremental APIs.
 - Bit-for-bit compatible XXH3-64 and XXH3-128 with one-shot and native batch APIs.
 - Caller-managed `*_into` outputs for allocation-sensitive workloads.
 - Runtime dispatch across AVX-512, AVX2, SSE4.1, SSSE3, NEON, and scalar implementations where applicable.
 - Direct CPython buffer handling for `bytes`, `bytearray`, and `memoryview` inputs.
-- Install wheels for CPython 3.10 through 3.15 and free-threaded CPython
-  3.14t and 3.15t on Linux, macOS, and Windows.
-
-## Citation
-
-If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).
+- Install wheels for CPython 3.10 through 3.15 and free-threaded CPython 3.14t and 3.15t on Linux, macOS, and Windows.
 
 ## Installation
 
@@ -35,21 +37,6 @@ If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).
 pip3 install hashcodecs
 ```
 
-## Compatibility
-
-Version 1.x keeps the documented Python API stable under the
-[compatibility policy](docs/compatibility.md). Release wheels target CPython 3.10 through 3.15 on manylinux x86-64,
-macOS 11+ ARM64, and Windows x86-64. CPython 3.14t and 3.15t receive free-threaded wheels on the same platforms.
-
-The Rust crate and Python package share one release version. Before 1.0, minor releases may contain breaking Rust API
-changes; the documented Python API follows the compatibility policy below.
-See [Security Policy](SECURITY.md) for vulnerability reporting.
-
-## Performance snapshot
-
-On the benchmark host, `hashcodecs.xxh3_64` processes a 1 MiB input at 78.83 GiB/s. The operator pinned one logical
-CPU and measured hashcodecs alone. At 256 B items in batches of 64, the Base64 batch API reaches 8.56 GiB/s for encode and 7.60 GiB/s for decode. The per-item loop reaches 4.41 and 3.39 GiB/s. Read the [benchmark details](BENCHMARK.md) and [raw results](docs/benchmarks/results.csv).
-
 ## Python
 
 The Base64 module follows familiar Python conventions while adding explicit padding, canonical validation, batch,
@@ -132,10 +119,14 @@ assert_eq!(
 
 ## Architecture
 
-The Rust core owns algorithm behavior and SIMD dispatch. A thin CPython layer handles argument parsing, buffer
+The Rust core owns algorithm behavior and SIMD dispatch. A substantial CPython layer handles argument parsing, buffer
 ownership, reusable outputs, and GIL decisions; root-level Python modules provide typed public exports without
 adding per-call wrappers.
 
+Each Rust algorithm exposes a small public façade. Base64 groups internals by encode and decode operation and
+places ISA kernels such as `encode/avx2.rs` and `decode/ssse3.rs` under their operation. MurmurHash3 groups code by
+canonical variant. XXH3 uses processing-stage modules, with long-input ISA kernels under `xxhash/long/`.
+
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the module layout, dispatch model, algorithm data flows,
 CPython boundary, and safety invariants.
 
@@ -191,12 +182,14 @@ 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_batch.py
+uv run --no-project --with . python benchmarks/python_calls.py
 uv run --no-project --with . python benchmarks/python_murmur3.py
 uv run --no-project --with . python benchmarks/python_xxhash.py
 ```
 
-The Python benchmarks expose focused modes such as `--into`, `--bytearray-input`, `--memoryview-input`,
-`--incremental`, `--large`, and `--hashcodecs-only`. Use `--help` on a benchmark script for its supported modes.
+The Python benchmarks expose focused modes such as `--into`, `--lenient`, `--bytearray-input`, `--memoryview-input`,
+`--sliced-memoryview-input`, `--incremental`, `--large`, and `--hashcodecs-only`. All scripts also accept `--samples` and
+`--minimum-sample-seconds`; use `--help` on a benchmark script for its supported modes and defaults.
 
 For the same-ISA Windows XXH3 comparison shown above, rebuild the C baseline with:
 
@@ -206,6 +199,13 @@ cargo clean -p xxhash-c-sys
 cargo bench --bench xxhash
 ```
 
+## Performance snapshot
+
+In the full 2026-08-23 hashcodecs-only run on the benchmark host, `hashcodecs.xxh3_64` processes a 1 MiB input at
+79.20 GiB/s. With 256 B items in batches of 64, the Base64 batch API reaches 8.80 GiB/s for encode and 7.58 GiB/s for
+decode. The run pins one logical CPU and uses 15 samples with a 0.2-second minimum per sample. Read the
+[benchmark details](BENCHMARK.md) and [raw comparison results](docs/benchmarks/results.csv).
+
 ## Development
 
 Build the Python wheel and source distribution:
@@ -228,15 +228,21 @@ uv run --frozen --no-sync pytest tests --cov=hashcodecs --cov-branch --cov-fail-
 Optimized paths are also checked with differential fuzzing, Kani, strict-provenance Miri, AddressSanitizer, and
 MemorySanitizer in CI.
 
+## Compatibility
+
+Version 1.x keeps the documented Python API stable under the
+[compatibility policy](docs/compatibility.md). Release wheels target CPython 3.10 through 3.15 on manylinux x86-64,
+macOS 11+ ARM64, and Windows x86-64. CPython 3.14t and 3.15t receive free-threaded wheels on the same platforms.
+
+The Rust crate and Python package share one release version. The documented Python API follows the compatibility
+policy below. See [Security Policy](SECURITY.md) for vulnerability reporting.
+
 ## References
 
 The Base64 SIMD implementation follows the approach described in
 [Faster Base64 Encoding and Decoding using AVX2 Instructions](https://arxiv.org/abs/1704.00605), extended with
 runtime-selected AVX-512 VBMI and AArch64 NEON backends.
 
-## License
-
-Licensed under either of the following, at your option:
+## Citation
 
-- [Apache License 2.0](LICENSE)
-- [MIT License](LICENSE-MIT)
+If you use `hashcodecs`, cite [CITATION.cff](CITATION.cff).

{hashcodecs-1.0.0 → hashcodecs-1.2.0}/benches/xxhash.rs

@@ -6,7 +6,18 @@ use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_m
 
 mod support;
 
-const SIZES: [usize; 5] = [64, 1024, 4 * 1024, 1024 * 1024, 8 * 1024 * 1024];
+const SIZES: [usize; 10] = [
+    64,
+    241,
+    512,
+    768,
+    1024,
+    1536,
+    2048,
+    4 * 1024,
+    1024 * 1024,
+    8 * 1024 * 1024,
+];
 
 fn data(size: usize, salt: u8) -> Vec<u8> {
     (0..size)
@@ -61,52 +72,55 @@ fn one_shot(c: &mut Criterion) {
 }
 
 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));
+    for items in [2, 3, 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/{items}_items/{size}"));
+            group.throughput(Throughput::Bytes((size * items) as u64));
 
-        group.bench_with_input(
-            BenchmarkId::new("hashcodecs_64", ITEMS),
-            &inputs,
-            |bench, inputs| bench.iter(|| hashcodecs::xxhash::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::xxhash::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();
+            group.bench_with_input(
+                BenchmarkId::new("hashcodecs_64", items),
+                &inputs,
+                |bench, inputs| {
+                    bench.iter(|| hashcodecs::xxhash::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::xxhash::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();
+        }
     }
 }