[][src]Struct blake3::Hasher

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());

Methods

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();

pub fn finalize(&self) -> Hash[src]

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.

Important traits for OutputReader
pub fn finalize_xof(&self) -> OutputReader[src]

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.

Trait Implementations

impl BlockInput for Hasher[src]

type BlockSize = U64

impl Clone for Hasher[src]

impl Debug for Hasher[src]

impl Default for Hasher[src]

impl ExtendableOutput for Hasher[src]

type Reader = OutputReader

impl FixedOutput for Hasher[src]

type OutputSize = U32

impl Input for Hasher[src]

impl Mac for Hasher[src]

type OutputSize = U32

type KeySize = U32

impl Reset for Hasher[src]

impl Write for Hasher[src]

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

This is equivalent to update.

Auto Trait Implementations

impl RefUnwindSafe for Hasher

impl Send for Hasher

impl Sync for Hasher

impl Unpin for Hasher

impl UnwindSafe for Hasher

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<D> Digest for D where
    D: Input + FixedOutput + Reset + Clone + Default
[src]

type OutputSize = <D as FixedOutput>::OutputSize

impl<D> DynDigest for D where
    D: 'static + Input + FixedOutput + Reset + Clone
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.