rapidhash

rapidhash is a Rust implementation of the rapidhash algorithm, the official successor to wyhash, tuned for speed on both AMD64 and AArch64 without depending on vectorized or cryptographic hardware instructions. It passes every SMHasher and SMHasher3 quality test while outperforming wyhash and foldhash on throughput, and it’s already used inside Google’s Fuchsia OS, Turso DB, the metrics crate, and alloy-primitives.

The crate ships std::hash::Hasher-compatible RandomState, GlobalState, and SeedableState builders plus RapidHashMap/RapidHashSet type aliases for near drop-in use in place of the standard library’s default hasher, alongside stable, versioned V1/V2/V3 hash functions that are bit-for-bit compatible with the original C++ rapidhash implementation for cross-language use. It supports streaming and file hashing, is fully no_std and WASM-ready, and includes an installable CLI for hashing files or stdin from the shell.

What You Get

• RandomState, GlobalState, and SeedableState std::hash::BuildHasher implementations in fast and quality flavors
• RapidHashMap and RapidHashSet type aliases for drop-in use with HashMap/HashSet
• Stable, versioned V1/V2/V3 hash functions that are bit-compatible with the C++ rapidhash reference implementation
• Streaming and file hashing via RapidStreamHasherV3 and rapidhash_v3_file_seeded for constant-memory processing of large inputs
• no_std and wasm32-unknown-unknown support, with optional getrandom v0.3/v0.4 backed entropy seeding
• An installable command-line tool (cargo install rapidhash) for hashing files or piped stdin

Common Use Cases

• Replacing the default SipHash in performance-sensitive Rust HashMaps and HashSets
• Producing hashes in Rust that must exactly match a C++ rapidhash implementation for shared caches, dedup keys, or wire formats
• Hashing in no_std or WASM environments, including browser targets that need OS-backed entropy via getrandom
• Streaming large files or piped stdin data without loading the full input into memory
• Quick ad hoc hashing of files from the shell via the bundled CLI

Under The Hood

Architecture The repository is a Cargo workspace of five crates: the core rapidhash library, rapidhash-c (C bindings used to cross-validate output against the reference implementation), rapidhash-bench/rapidhash-bench-wasm (benchmark harnesses), and rapidhash-msrv (an MSRV- and struct-size-focused crate excluded from the main workspace). Inside rapidhash/src, each algorithm generation lives in its own module (v1/, v2/, v3/, each with mod.rs, rapid_const.rs, rapid_file.rs, and seed.rs), while shared generic hasher machinery sits in inner/ (rapid_hasher.rs, seeding.rs, state/) and platform-level read/mix primitives live in util/. The public-facing fast.rs and quality.rs modules specialize that generic machinery into two named hasher flavors, collections.rs layers RapidHashMap/RapidHashSet on top via std::hash::BuildHasher, and main.rs is a separate std-gated CLI entry point. This is a clean layered design where the three algorithm versions are isolated per-module but share common mixing primitives in util/mix.rs, meaning a change to core mixing logic ripples through all three versions and the C-compatibility tests.

Tech Stack Pure Rust (edition 2021, MSRV 1.71.0) with no mandatory runtime dependency beyond rustversion for compile-time version gating. Optional dependencies are feature-gated: rand_core 0.9 for the deprecated rng feature, and dual-versioned getrandom v0.3/v0.4 (kept separate to avoid forcing a major version bump on every getrandom release) for OS/platform entropy in no_std contexts. Dev-dependencies include rapidhash-c (its own build.rs-driven C FFI crate), rand, rapidrand, tempfile, and assert_cmd for CLI integration testing. CI, run via GitHub Actions, exercises an unusually wide matrix for a crate this size: std and no_std builds, the unsafe feature in isolation, nightly-only features, 32-bit (i686) and embedded (thumbv6m, no-atomics) targets, the pinned MSRV via the dedicated rapidhash-msrv sub-crate, wasm32 targets including entropy-source behavior, C implementation parity, rustdoc tests, and compile-time struct-size assertions across six target triples to catch alignment regressions.

Code Quality The crate has 56 #[test] functions spread across 17 files, including a dedicated tests/cli.rs integration suite built on assert_cmd that runs the installed binary against stdin and file input and checks its output against the library functions directly. The public API is held to #![deny(missing_docs)] and #![deny(unused_must_use)], so undocumented public items and silently dropped Results fail the build rather than the review. The one block of unsafe code — used to skip redundant bounds checks for a small throughput gain — is opt-in behind its own Cargo feature with a dedicated CI job testing it in isolation from the safe default path.

API Design The crate layers its API by need: casual users get RapidHashMap/RapidHashSet as near drop-in replacements for the standard library’s collections behind a single import, while callers needing cross-language stability reach for explicit versioned functions (rapidhash_v1, v3::rapidhash_v3_seeded) with documented compatibility guarantees against the C++ implementation, and streaming consumers get RapidStreamHasherV3/rapidhash_v3_file_seeded for constant-memory hashing of large inputs. Naming is predictable — *_seeded, *_file_seeded, and *_inline suffixes signal variants consistently — and the bundled CLI produces output directly comparable to the library’s own hash values, which is a useful debugging touch. Deprecated features (rand, rng) are marked as such in the source with a stated removal plan rather than silently dropped, and the common case (RapidHashMap::default()) needs almost no boilerplate to adopt.