rustc-hash

rustc-hash provides FxHasher, a speedy, non-cryptographic hashing algorithm originally extracted from Firefox and now maintained as the default hasher used internally by the Rust compiler (rustc). Because DOS-resistance is irrelevant inside a trusted compiler pipeline, FxHasher trades SipHash’s cryptographic guarantees for raw speed, using a simple polynomial multiplication mixed with a bit rotation, plus a dedicated wyhash-inspired routine for hashing byte strings and slices.

The crate exposes drop-in FxHashMap and FxHashSet type aliases around std’s HashMap and HashSet, along with FxBuildHasher, seeded and randomized state variants (FxSeededState, FxRandomState), and full no_std support, making it a near-zero-effort swap for any Rust project that hashes untrusted-free keys — integers, small structs, or short strings — and wants to shave meaningful CPU cycles off hot-path hashing.

What You Get

• FxHasher — a fast polynomial-mix hasher with a dedicated byte/slice hashing routine designed for low collision rates on short keys
• FxHashMap and FxHashSet type aliases that drop in for std::collections::HashMap/HashSet with zero API changes
• FxBuildHasher, FxSeededState, and (behind the rand feature) FxRandomState for deterministic, seeded, or randomized hashing behavior
• no_std support via the default-off std feature toggle, so the hasher core can be used in embedded or kernel-level Rust code

Common Use Cases

• Compiler and tooling internals - Rust compilers, linters, and build tools that hash large numbers of trusted keys (spans, symbols, node IDs) and need every cycle back from hashing overhead.
• Hot-path lookup tables - Application code with performance-critical HashMap/HashSet lookups over integers or short strings where DOS resistance from untrusted input isn’t a concern.
• Embedded and no_std projects - Firmware or kernel-level Rust that needs a hasher without pulling in std, using FxHasher directly with a custom collection type.
• Deterministic testing and caching - Codebases that want reproducible hash iteration order via FxSeededState for snapshot tests or reproducible builds.

Under The Hood

Architecture: rustc-hash is architected as a single-purpose crate around one core primitive, FxHasher (src/lib.rs), which implements std::hash::Hasher by accumulating a usize hash state via wrapping-multiply-add per integer write and a separate multiply_mix + hash_bytes routine (a wyhash-inspired construction operating on 16-byte chunks with an s0/s1 two-stream design) for byte slices and strings; the finish() step performs one bit rotation to move entropy from the high bits (favored by multiplicative hashing) down into the low bits that hashbrown’s bucket indexing reads. Around this core, the crate layers three thin adapter modules: the root module exposes FxBuildHasher (a zero-sized BuildHasher producing the default-seeded FxHasher) and the FxHashMap/FxHashSet type aliases; src/seeded_state.rs adds FxSeededState for explicit user-supplied seeds via FxHashMapSeed/FxHashSetSeed; and src/random_state.rs (gated behind the optional rand feature) adds FxRandomState, which caches a thread-local seed via Cell and increments it on every construction, mirroring std’s RandomState default behavior. Feature flags (std, rand, nightly) gate std-only collection aliases, the rand-dependent random state, and const-trait/derive_const nightly optimizations respectively, keeping the no_std core hasher independent of any allocator or platform assumption.

Tech Stack: The crate has effectively zero runtime dependencies in its default configuration — the entire hasher core (src/lib.rs) depends only on core::hash and, when the std feature is enabled (default), std::collections::{HashMap, HashSet}. The single optional dependency is rand 0.9, pulled in only behind the opt-in rand feature to power FxRandomState’s thread-local seed generation; the crate ships no build scripts, no proc-macros, and no non-Rust code (100% Rust per GitHub’s language breakdown). It targets edition 2021 and a rust-version floor of 1.77, and uses nightly-gated features (const_default, const_trait_impl, derive_const, hasher_prefixfree_extras) purely to make FxHasher’s Default impl and write_length_prefix/write_str hooks const/no-op on nightly toolchains, with stable fallbacks via cfg_attr — this is characteristic of a crate maintained in lockstep with rustc’s own compiler internals rather than a general application dependency.

Code Quality: Testing lives entirely in #[cfg(test)] inline modules across the three source files rather than a separate tests/ directory. src/lib.rs’s test module hard-codes exact expected hash outputs for every integer width (u8 through u128, signed and unsigned) and several byte-string inputs, split by 32-bit vs 64-bit target_pointer_width, which pins the hash algorithm’s exact output and would catch any accidental behavior change; it also has a with_seed_actually_different test asserting two seeded hashers never collide across the full u8 range. src/random_state.rs and src/seeded_state.rs each test clone-equality and distinctness of their state seeds, including a cross-thread test for FxRandomState. There’s no fuzzing harness or property-based testing (no proptest/quickcheck dependency), and error handling is essentially absent because the API surface has no fallible operations — the only panic-shaped code path (a try_into().unwrap() in hash_bytes) is guarded by length checks immediately prior, and the CHANGELOG notes a prior PR explicitly removed an unreachable panic. Naming is consistent and idiomatic (Fx-prefixed types mirroring std’s Hash-prefixed ones), and every public item carries a doc comment.

API Design: The public API is intentionally tiny and deliberately mirrors std’s own hashing traits: FxHashMap<K, V> and FxHashSet<V> are direct type aliases for HashMap/HashSet parameterized with FxBuildHasher, so adopting the crate is a one-line import-and-replace with no new methods to learn — the doc comment’s usage example is exactly let mut map: FxHashMap<u32, u32> = FxHashMap::default();. Seeded and randomized variants (FxHashMapSeed/FxSeededState, FxHashMapRand/FxRandomState) extend the same pattern rather than introducing new concepts, and FxHasher itself directly implements the standard core::hash::Hasher trait so it composes with any code generic over Hasher/BuildHasher. The crate’s only friction points are its feature-flag surface (std/rand/nightly need to be understood to reach the randomized or no_std variants) and a lack of runnable examples beyond the doc-tests embedded in rustdoc comments — but for a hashing primitive with essentially one job, the near-zero boilerplate and drop-in compatibility with std collections make this a best-in-class developer experience for its scope.