Skip to content

feat: complete and qualify hash variant APIs - #13

Merged
tisonkun merged 10 commits into
mainfrom
codex/clarify-murmur-variants
Sep 2, 2026
Merged

feat: complete and qualify hash variant APIs#13
tisonkun merged 10 commits into
mainfrom
codex/clarify-murmur-variants

Conversation

@tisonkun

@tisonkun tisonkun commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Implement all three original MurmurHash3 variants as allocation-free one-shot and streaming APIs.
  • Name MurmurHash3 and XXH3 functions, states, and builders with their exact algorithm variants so callers do not need to remember an implicit default.
  • Give complete-input hashing and incremental hashing separate, consistent entry points: module-level functions hash complete byte slices, while state types provide update, digest, and integration traits.
  • Remove duplicate and legacy names without compile-time or rustdoc aliases; the renamed crate is presented as a fresh API.

Design Notes

MurmurHash3 now maps directly to the three names defined by the reference implementation:

Variant One-shot Streaming Builder
x86_32 murmur3_x86_32 Murmur3X86_32 Murmur3X86_32Builder
x86_128 murmur3_x86_128 Murmur3X86_128
x64_128 murmur3_x64_128 Murmur3X64_128

The x86 and x64 labels select incompatible digest algorithms rather than restricting the Rust implementation to those target architectures; all three implementations are portable. The new x86_128 implementation follows the reference four-lane block, tail, and finalization order. Its one-shot and streaming results are checked against murmur3 0.5.2 across every length through 2 KiB, randomized inputs through 128 KiB, arbitrary streaming chunks, every two-way split through 257 bytes, and multiple seeds.

XXH3 likewise exposes xxh3_64 / Xxh3_64 and xxh3_128 / Xxh3_128. Xxh3_64Builder and Xxh3_64SecretBuilder are width-qualified because BuildHasher constructs only the 64-bit state. Xxh3Kernel, Xxh3SecretTooShort, and the secret constants remain unqualified because they are genuinely shared by both output widths.

Why remove associated one-shot methods?

A complete byte slice has one entry point: the corresponding module-level function. The removed state-associated methods were one-line forwarding wrappers with no state, configuration, validation, or behavior of their own. Keeping both forms made the API appear to offer two hashing modes and doubled the places users had to compare in rustdoc.

For FNV-1a specifically:

  • Fnv1a32::oneshot(input) is covered by fnv1a_32(input).
  • Fnv1a32::oneshot_with_offset_basis(input, basis) is covered by fnv1a_32_with_offset_basis(input, basis).
  • Fnv1a64::oneshot(input) is covered by fnv1a_64(input).
  • Fnv1a64::oneshot_with_offset_basis(input, basis) is covered by fnv1a_64_with_offset_basis(input, basis).

The state constructors, custom offset bases, update, digest, reset, builders, Hasher, and std::io::Write remain because they represent distinct configuration or integration capabilities. The same rule is applied consistently to MurmurHash3 and xxHash state-associated one-shot forwarding methods.

Validation

  • cargo x lint
  • cargo x check
  • cargo x test
  • One-shot x86_128 benchmark at 4 KiB / 1 MiB: rache median 8.70 / 8.81 GB/s; murmur3 reference path 4.47 / 4.56 GB/s on the development host

MurmurHash3 defines separate x86_128 and x64_128 algorithms, so describing the architecture-qualified function as merely an alias hides important disambiguation. Present x64_128 as the implemented variant, identify murmur3_128 as the shorter equivalent name, and state that x86_128 is not implemented.
The 0.1 API exposed module-level one-shot functions alongside state-associated forwarding methods, and also retained alternate names for MurmurHash3 x64_128, the XXH3-64 state, and 128-bit digests. Those paths describe the same operations and make the capability map look larger than the implementation really is.\n\nKeep the reference-qualified MurmurHash3 names, Xxh3 for the conventional 64-bit state, digest for every state result, and module-level functions for complete input. Rustdoc aliases preserve discovery of the retired spellings without keeping duplicate compile-time APIs.
@tisonkun tisonkun changed the title docs: distinguish MurmurHash3 variant names refactor: standardize public hash names Sep 2, 2026
The existing 128-bit helper names did not identify whether they implemented the x86 or x64 MurmurHash3 variant. That ambiguity becomes error-prone once both algorithms live in the same module.\n\nQualify the constants, lane mixers, block consumer, and finalizer as x64_128 before adding the separate x86_128 path. This is a naming-only change with no public API or behavior change.
Rache exposed x86_32 and x64_128 but omitted the third algorithm in the original MurmurHash3 family. That gap made the architecture-qualified names harder to explain and prevented interoperability with x86_128 digests.\n\nAdd allocation-free one-shot and streaming APIs under the unique murmur3_x86_128 and Murmur3X86_128 names. Share the common 16-byte streaming buffer path with x64_128, cover the new variant through the existing reference, partition, I/O, and benchmark matrices, and keep both 128-bit algorithms distinct in the capability documentation.
@tisonkun tisonkun changed the title refactor: standardize public hash names feat: complete the MurmurHash3 variant family Sep 2, 2026
The renamed crate is being presented as a fresh release, so preserving vocabulary from the old crate in rustdoc search would add ambiguity without serving a supported migration path.
The x64_128 documentation still claimed x86_128 was unavailable after that variant was implemented. Directly link the two distinct algorithms so callers can choose deliberately.
Rache exposes separate streaming states for the 64-bit and 128-bit XXH3 algorithms, so an unqualified Xxh3 name incorrectly suggests a shared or default state. Match xxh3_64 with Xxh3_64 and make the output width discoverable without relying on convention.
Both builders construct only Xxh3_64 states because BuildHasher returns u64. Naming them Xxh3_64Builder and Xxh3_64SecretBuilder keeps the algorithm width explicit and matches the state they build.
The completed MurmurHash3 family exposes three distinct reference variants. Naming the 32-bit API murmur3_x86_32, Murmur3X86_32, and Murmur3X86_32Builder removes the only variant-name exception and makes all three mappings predictable.
The explicit XXH3 and MurmurHash3 names change rustfmt line wrapping and lexical import order. Apply only those mechanical adjustments so the naming commits remain easy to inspect.
@tisonkun tisonkun changed the title feat: complete the MurmurHash3 variant family feat: complete and qualify hash variant APIs Sep 2, 2026
@tisonkun
tisonkun marked this pull request as ready for review September 2, 2026 09:39
@tisonkun
tisonkun merged commit bc62587 into main Sep 2, 2026
9 checks passed
@tisonkun
tisonkun deleted the codex/clarify-murmur-variants branch September 2, 2026 09:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant