Struct blake3::Hasher[−][src]

pub struct Hasher { /* fields omitted */ }

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

In addition to its inherent methods, this type implements several commonly used traits from the digest and crypto_mac crates.

Performance note: The update and update_with_join methods perform poorly when the caller’s input buffer is small. See their method docs below. A 16 KiB buffer is large enough to leverage all currently supported SIMD instruction sets.

Examples

// Hash an input incrementally.
let mut hasher = blake3::Hasher::new();
hasher.update(b"foo");
hasher.update(b"bar");
hasher.update(b"baz");
assert_eq!(hasher.finalize(), 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], blake3::hash(b"foobarbaz").as_bytes());

Implementations

`impl Hasher`[src]

`pub fn new() -> Self`[src]

Construct a new Hasher for the regular hash function.

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

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

`pub fn new_derive_key(context: &str) -> Self`[src]

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`[src]

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. However, depending on how much inlining the optimizer does, moving a Hasher might copy its entire CV stack, most of which is useless uninitialized bytes. This methods avoids that copy.

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

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

This method is always single-threaded. For multi-threading support, see update_with_join below.

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_with_join<J: Join>(&mut self, input: &[u8]) -> &mut Self`[src]

Add input bytes to the hash state, as with update, but potentially using multi-threading. See the example below, and the join module for a more detailed explanation.

To get any performance benefit from multi-threading, the input buffer size needs to be very large. As a rule of thumb on x86_64, there is no benefit to multi-threading inputs less than 128 KiB. Other platforms have different thresholds, and in general you need to benchmark your specific use case. Where possible, memory mapping an entire input file is recommended, to take maximum advantage of multi-threading without needing to tune a specific buffer size. Where memory mapping is not possible, good multi-threading performance requires doing IO on a background thread, to avoid sleeping all your worker threads while the input buffer is (serially) refilled. This is quite complicated compared to memory mapping.

Example

// Hash a large input using multi-threading. Note that multi-threading
// comes with some overhead, and it can actually hurt performance for small
// inputs. The meaning of "small" varies, however, depending on the
// platform and the number of threads. (On x86_64, the cutoff tends to be
// around 128 KiB.) You should benchmark your own use case to see whether
// multi-threading helps.
let input: &[u8] = some_large_input();
let mut hasher = blake3::Hasher::new();
hasher.update_with_join::<blake3::join::RayonJoin>(input);
let hash = hasher.finalize();