Lib.rs

Cargo Features

[dependencies]
blake3 = { version = "1.5.5", default-features = false, features = ["neon", "std", "rayon", "mmap", "zeroize", "traits-preview", "digest", "pure", "prefer_intrinsics", "no_sse2", "no_neon", "serde"] }

default = std

The std feature is set by default whenever blake3 is added without default-features = false somewhere in the dependency tree.

neon

The NEON implementation does not participate in dynamic feature detection,
which is currently x86-only. If "neon" is on, NEON support is assumed. Note that AArch64 always supports NEON, but support on ARMv7 varies. The NEON implementation uses C intrinsics and requires a C compiler.

std default mmap? rayon?

This crate uses libstd for std::io trait implementations, and also for runtime CPU feature detection. This feature is enabled by default. If you use --no-default-features, the only way to use the SIMD implementations in this
crate is to enable the corresponding instruction sets statically for the entire build, with e.g. RUSTFLAGS="-C target-cpu=native".

rayon = std

The rayon feature (disabled by default, but enabled for docs.rs) adds the update_rayon and (in combination with mmap below) update_mmap_rayon methods, for multithreaded hashing. However, even if this feature is enabled, all other APIs remain single-threaded.

Implementation detail: We take a dependency on rayon-core instead of rayon, because it builds faster and still includes all the APIs we need.

Enables rayon-core

Affects join::RayonJoin…

mmap = std

The mmap feature (disabled by default, but enabled for docs.rs) adds the update_mmap and (in combination with rayon above) update_mmap_rayon helper methods for memory-mapped IO.

Enables memmap2

zeroize

Implement the zeroize::Zeroize trait for types in this crate.

Enables zeroize, zeroize of arrayvec

traits-preview

This crate implements traits from the RustCrypto project, exposed here as the "traits-preview" feature. However, these traits aren't stable, and they're
expected to change in incompatible ways before they reach 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 of this crate. (The "*-preview" feature name follows the conventions of the RustCrypto "signature" crate.)

Enables digest

Affects blake3::traits…

digest

---------- Features below this line are undocumented and unstable. ---------- The following features are mainly intended for testing and benchmarking, and they might change or disappear at any time without a major version bump.

It wasn't originally intended to expose "digest" as its own feature, but the traits-preview feature above predated the "dep:" syntax in Cargo. Version 1.5.2 of this crate started using "dep:" syntax, but that broke some callers in the wild (https://solana.stackexchange.com/q/17787/29050). This feature unbreaks those callers. When Cargo gains the ability to deprecate features, this feature will be deprecated. Note that the relevant trait implementations are still gated by "traits-preview".

Enables digest

pure

By default on x86_64, this crate uses Samuel Neves' hand-written assembly implementations for SSE4.1, AVX2, and AVX512. (These provide both the best runtime performance, and the fastest build times.) And by default on 32-bit x86, this crate uses Rust intrinsics implementations for SSE4.1 and AVX2, and a C intrinsics implementation for AVX-512. In both cases, if a C compiler is not detected, or if AVX-512 support is missing from the detected compiler,
build.rs automatically falls back to a pure Rust build. This feature forces that fallback, for testing purposes. (Note that in CI testing, we set the BLAKE3_CI environment variable, which instructs build.rs to error out rather than doing an automatic fallback.)

prefer_intrinsics

As described above, on x86_64 this crate use assembly implementations by default. Enabling the "prefer_intrinsics" feature makes this crate use intrinsics implementations on both 32-bit and 64-bit x86, again for testing purposes.

no_sse2

Disable individual instruction sets. CI testing uses these flags to simulate different levels of hardware SIMD support. Note that code for the corresponding instruction set is still compiled; only detection is disabled.

As noted above, these flags are *for testing only* and are not stable. It's possible that some users might find that their particular use case performs better if e.g. AVX-512 is disabled, because of issues like CPU downclocking.
If that comes up, and if disabling the instruction set here at the feature level turns out to be the right approach, then we can design a stable feature. Until then, we reserve the right to break these features in a patch release.

no_sse41 no_avx2 no_avx512 no_neon

Features from optional dependencies

serde implicit feature

Enables serde

serde:

A generic serialization/deserialization framework