feat(hash): XXH3-64, container functor adapters, CombineHashes, TODO roadmap - #215
Merged
Conversation
The two-seed fallback was only as strong as the algorithm's seed handling: seed-affine hashes collide both lanes together and seed-ignoring ones produced h1 == h2. The second pass now skips the first up-to-8 bytes and injects them (with kSeedFlip) into its seed, so both lanes cover every input byte yet hash different data -- the lanes decorrelate even for algorithms with weak or ignored seed handling, at unchanged cost. Alternatives considered: a plain +8 shift leaves lane 2 blind to the first 8 bytes (structural collision class for any algorithm); a half/half split is 2x faster but each output bit would depend on only half the input.
…roadmap Batch from the state-of-the-art gap analysis (see mbo/hash/TODO.md): - XXH3 (64-bit): constexpr-safe scalar implementation of the modern xxHash generation, transcribed from the reference implementation v0.8.2 (192-byte kSecret byte-for-byte; all dispatch classes 0/1-3/4-8/9-16/17-128/129-240/ long incl. blocks, scramble, and the seeded custom-secret path). Canonical XXH3_64bits[_withSeed] values pinned by 34 reference vectors across every class boundary. Registered as xxh3::Algorithm; benchmark: fastest at 64B (15.6 GiB/s) and 4KB (21.5 GiB/s) on Apple clang. - hash_internal::Mul128Fold64: constexpr 64x64->128 fold (uint128 where available, portable 32-bit schoolbook otherwise) - also unblocks a future wyhash-class algorithm. - Hasher<Algo> is now a transparent functor (operator() + is_transparent): drops directly into absl/std hash containers with heterogeneous string_view lookup. - mbo::hash::CombineHashes(uint64_t, uint64_t): order-dependent, well-mixed combine. - mbo/hash/TODO.md: the prioritized roadmap from the gap analysis (easy / medium / hard / non-goals), maintained in-repo.
# Conflicts: # CHANGELOG.md # README.md
Fab-Cat
approved these changes
Jul 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Batch 1 from the state-of-the-art gap analysis (mbo/hash/TODO.md).
XXH3 (64-bit) —
xxh3::AlgorithmConstexpr-safe scalar implementation of the modern xxHash generation, transcribed from the reference implementation v0.8.2 (secret byte-for-byte, all dispatch classes: 0 / 1–3 / 4–8 / 9–16 / 17–128 / 129–240 / long with 1024-byte blocks + scramble + seeded custom-secret path). Canonical
XXH3_64bits[_withSeed]values pinned by 34 reference vectors covering every class boundary (× seeds 0/5381).New
hash_internal::Mul128Fold64(constexpr__uint128_twhere available, portable 32-bit schoolbook otherwise) — the xxh3/wyhash-family core, so a future wyhash-class algorithm is now unblocked.Container functor adapters
Hasher<Algo>is now a transparent functor (operator()+is_transparent):absl::flat_hash_map<std::string, V, mbo::hash::DefaultHasher, std::equal_to<>> map; map.find(std::string_view(...)); // heterogeneous, no temporary std::stringCombineHashes
mbo::hash::CombineHashes(uint64_t, uint64_t)— order-dependent,Fmix64-finalized golden-ratio combine.Roadmap
mbo/hash/TODO.mdrecords the gap analysis (easy/medium/hard/non-goals) in-repo; done items removed per its policy.Algorithm comparison (CI benchmark, this branch)
All cells: throughput in GiB/s (mean of 3); bracketed factor is relative to xxh64 in the same row (xxh64 = 1.00x). Bold marks the fastest algorithm per size.
ubuntu-latest (x86_64, gcc)
macos-26 (arm64, Apple clang)
Reading
fnv1astill wins the 1-byte corner;simplethe 4 B corner on macOS.All typed framework tests cover xxh3 automatically (avalanche 0.45–0.55 at every tier incl. the >240 B long path, collisions, constexpr==runtime, width detection).