Module blake3::join

The multi-threading abstractions used by Hasher::update_with_join.

Different implementations of the Join trait determine whether Hasher::update_with_join performs multi-threading on sufficiently large inputs. The SerialJoin implementation is single-threaded, and the RayonJoin implementation (gated by the rayon feature) is multi-threaded. Interfaces other than Hasher::update_with_join, like hash and Hasher::update, always use SerialJoin internally.

The Join trait is an almost exact copy of the rayon::join API, and RayonJoin is the only non-trivial implementation provided. The only difference between the function signature in the Join trait and the underlying one in Rayon, is that the trait method includes two length parameters. This gives an implementation the option of e.g. setting a subtree size threshold below which it keeps splits on the same thread. However, neither of the two provided implementations currently makes use of those parameters. Note that in Rayon, the very first join call is more expensive than subsequent calls, because it moves work from the calling thread into the thread pool. That makes a coarse-grained input length threshold in the caller more effective than a fine-grained subtree size threshold after the implementation has already started recursing.

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

Enums

RayonJoin	The Rayon-based implementation of Join. The left and right sides are executed on the Rayon thread pool, potentially in parallel. This implementation is gated by the rayon feature, which is off by default.
SerialJoin	The trivial, serial implementation of Join. The left and right sides are executed one after the other, on the calling thread. The standalone hashing functions and the Hasher::update method use this implementation internally.

Traits

Join	The trait that abstracts over single-threaded and multi-threaded recursion.