Struct iroh_blake3::Hasher

pub struct Hasher { /* private fields */ }

An incremental hash state that can accept any number of writes.

When the traits-preview Cargo feature is enabled, this type implements several commonly used traits from the digest crate. However, those traits aren’t stable, and they’re expected to change in incompatible ways before that crate reaches 1.0. For that reason, this crate makes no SemVer guarantees for this feature, and callers who use it should expect breaking changes between patch versions.

When the rayon Cargo feature is enabled, the update_rayon method is available for multithreaded hashing.

Performance note: The update method can’t take full advantage of SIMD optimizations if its input buffer is too small or oddly sized. Using a 16 KiB buffer, or any multiple of that, enables all currently supported SIMD instruction sets.

Examples

// Hash an input incrementally.
let mut hasher = iroh_blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
assert_eq!(hasher.finalize(), iroh_blake3::hash(b"foobarbaz"));

// Extended output. OutputReader also implements Read and Seek.
let mut output = [0; 1000];
let mut output_reader = hasher.finalize_xof();
output_reader.fill(&mut output);
assert_eq!(&output[..32], iroh_blake3::hash(b"foobarbaz").as_bytes());

Implementations

impl Hasher

pub fn new() -> Self

Construct a new Hasher for the regular hash function.

pub fn new_keyed(key: &[u8; 32]) -> Self

Construct a new Hasher for the keyed hash function. See keyed_hash.

pub fn new_derive_key(context: &str) -> Self

Construct a new Hasher for the key derivation function. See derive_key. The context string should be hardcoded, globally unique, and application-specific.

pub fn reset(&mut self) -> &mut Self

Reset the Hasher to its initial state.

This is functionally the same as overwriting the Hasher with a new one, using the same key or context string if any.

pub fn update(&mut self, input: &[u8]) -> &mut Self

Add input bytes to the hash state. You can call this any number of times.

This method is always single-threaded. For multithreading support, see update_rayon below (enabled with the rayon Cargo feature).

Note that the degree of SIMD parallelism that update can use is limited by the size of this input buffer. The 8 KiB buffer currently used by std::io::copy is enough to leverage AVX2, for example, but not enough to leverage AVX-512. A 16 KiB buffer is large enough to leverage all currently supported SIMD instruction sets.

pub fn update_rayon(&mut self, input: &[u8]) -> &mut Self

Identical to update, but using Rayon-based multithreading internally.

This method is gated by the rayon Cargo feature, which is disabled by default but enabled on docs.rs.

To get any performance benefit from multithreading, the input buffer needs to be large. As a rule of thumb on x86_64, update_rayon is slower than update for inputs under 128 KiB. That threshold varies quite a lot across different processors, and it’s important to benchmark your specific use case.

Memory mapping an entire input file is a simple way to take advantage of multithreading without needing to carefully tune your buffer size or offload IO. However, on spinning disks where random access is expensive, that approach can lead to disk thrashing and terrible IO performance. Note that OS page caching can mask this problem, in which case it might only appear for files larger than available RAM. Again, benchmarking your specific use case is important.

pub fn finalize(&self) -> Hash

Finalize the hash state and return the Hash of the input.

This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.

pub fn finalize_xof(&self) -> OutputReader

Finalize the hash state and return an OutputReader, which can supply any number of output bytes.

This method is idempotent. Calling it twice will give the same result. You can also add more input and finalize again.

pub fn count(&self) -> u64

Return the total number of bytes hashed so far.

Trait Implementations

impl Clone for Hasher

fn clone(&self) -> Hasher

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Hasher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Hasher

fn default() -> Self

Returns the “default value” for a type.

impl Write for Hasher

fn write(&mut self, input: &[u8]) -> Result<usize>

This is equivalent to update.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.