HDK
|
Classes | |
struct | XXH128_hash_t |
The return value from 128-bit hashes. More... | |
struct | XXH128_canonical_t |
Macros | |
#define | XXH3_SECRET_SIZE_MIN 136 |
Typedefs | |
typedef struct XXH3_state_s | XXH3_state_t |
The state struct for the XXH3 streaming API. More... | |
XXH3 is a more recent hash algorithm featuring:
Speed analysis methodology is explained here:
https://fastcompression.blogspot.com/2019/03/presenting-xxh3.html
Compared to XXH64, expect XXH3 to run approximately ~2x faster on large inputs and >3x faster on small ones, exact differences vary depending on platform.
XXH3's speed benefits greatly from SIMD and 64-bit arithmetic, but does not require it. Most 32-bit and 64-bit targets that can run XXH32 smoothly can run XXH3 at competitive speeds, even without vector support. Further details are explained in the implementation.
Optimized implementations are provided for AVX512, AVX2, SSE2, NEON, POWER8, ZVector and scalar targets. This can be controlled via the XXH_VECTOR macro. For the x86 family, an automatic dispatcher is included separately in xxh_x86dispatch.c.
XXH3 implementation is portable: it has a generic C90 formulation that can be compiled on any platform, all implementations generage exactly the same hash value on all platforms. Starting from v0.8.0, it's also labelled "stable", meaning that any future version will also generate the same hash value.
XXH3 offers 2 variants, _64bits and _128bits.
When only 64 bits are needed, prefer invoking the _64bits variant, as it reduces the amount of mixing, resulting in faster speed on small inputs. It's also generally simpler to manipulate a scalar return type than a struct.
The API supports one-shot hashing, streaming mode, and custom secrets.
#define XXH3_SECRET_SIZE_MIN 136 |
The bare minimum size for a custom secret.
Definition at line 941 of file UT_XXHash.h.
typedef struct XXH3_state_s XXH3_state_t |
The state struct for the XXH3 streaming API.
Definition at line 978 of file UT_XXHash.h.
XXH_PUBLIC_API void XXH128_canonicalFromHash | ( | XXH128_canonical_t * | dst, |
XXH128_hash_t | hash | ||
) |
XXH_PUBLIC_API XXH_PUREF int XXH128_cmp | ( | const void * | h128_1, |
const void * | h128_2 | ||
) |
Compares two XXH128_hash_t This comparator is compatible with stdlib's qsort()
/bsearch()
.
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH128_hashFromCanonical | ( | const XXH128_canonical_t * | src | ) |
XXH_PUBLIC_API XXH_PUREF int XXH128_isEqual | ( | XXH128_hash_t | h1, |
XXH128_hash_t | h2 | ||
) |
XXH128_isEqual(): Return: 1 if h1
and h2
are equal, 0 if they are not.
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits | ( | const void * | data, |
size_t | len | ||
) |
Unseeded 128-bit variant of XXH3.
The 128-bit variant of XXH3 has more strength, but it has a bit of overhead for shorter inputs.
This is equivalent to XXH3_128bits_withSeed() with a seed of 0, however it may have slightly better performance due to constant propagation of the defaults.
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_digest | ( | const XXH3_state_t * | statePtr | ) |
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset | ( | XXH3_state_t * | statePtr | ) |
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSecret | ( | XXH3_state_t * | statePtr, |
const void * | secret, | ||
size_t | secretSize | ||
) |
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSeed | ( | XXH3_state_t * | statePtr, |
XXH64_hash_t | seed | ||
) |
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_update | ( | XXH3_state_t * | statePtr, |
const void * | input, | ||
size_t | length | ||
) |
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecret | ( | const void * | data, |
size_t | len, | ||
const void * | secret, | ||
size_t | secretSize | ||
) |
Custom secret 128-bit variant of XXH3.
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSeed | ( | const void * | data, |
size_t | len, | ||
XXH64_hash_t | seed | ||
) |
Seeded 128-bit variant of XXH3.
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits | ( | const void * | input, |
size_t | length | ||
) |
64-bit unseeded variant of XXH3.
This is equivalent to XXH3_64bits_withSeed() with a seed of 0, however it may have slightly better performance due to constant propagation of the defaults.
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_digest | ( | const XXH3_state_t * | statePtr | ) |
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset | ( | XXH3_state_t * | statePtr | ) |
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSecret | ( | XXH3_state_t * | statePtr, |
const void * | secret, | ||
size_t | secretSize | ||
) |
XXH3_64bits_reset_withSecret(): secret
is referenced, it must outlive the hash streaming session. Similar to one-shot API, secretSize
must be >= XXH3_SECRET_SIZE_MIN
, and the quality of produced hash values depends on secret's entropy (secret's content should look like a bunch of random bytes). When in doubt about the randomness of a candidate secret
, consider employing XXH3_generateSecret()
instead (see below).
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSeed | ( | XXH3_state_t * | statePtr, |
XXH64_hash_t | seed | ||
) |
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_update | ( | XXH3_state_t * | statePtr, |
const void * | input, | ||
size_t | length | ||
) |
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSecret | ( | const void * | data, |
size_t | len, | ||
const void * | secret, | ||
size_t | secretSize | ||
) |
64-bit variant of XXH3 with a custom "secret".
It's possible to provide any blob of bytes as a "secret" to generate the hash. This makes it more difficult for an external actor to prepare an intentional collision. The main condition is that secretSize must be large enough (>= XXH3_SECRET_SIZE_MIN). However, the quality of the secret impacts the dispersion of the hash algorithm. Therefore, the secret must look like a bunch of random bytes. Avoid "trivial" or structured data such as repeated sequences or a text document. Whenever in doubt about the "randomness" of the blob of bytes, consider employing "XXH3_generateSecret()" instead (see below). It will generate a proper high entropy secret derived from the blob of bytes. Another advantage of using XXH3_generateSecret() is that it guarantees that all bits within the initial blob of bytes will impact every bit of the output. This is not necessarily the case when using the blob of bytes directly because, when hashing small inputs, only a portion of the secret is employed.
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSeed | ( | const void * | input, |
size_t | length, | ||
XXH64_hash_t | seed | ||
) |
64-bit seeded variant of XXH3
This variant generates a custom secret on the fly based on default secret altered using the seed
value.
While this operation is decently fast, note that it's not completely free.
input | The data to hash |
length | The length |
seed | The 64-bit seed to alter the state. |
XXH_PUBLIC_API void XXH3_copyState | ( | XXH3_state_t * | dst_state, |
const XXH3_state_t * | src_state | ||
) |
XXH_PUBLIC_API XXH_MALLOCF XXH3_state_t* XXH3_createState | ( | void | ) |
XXH_PUBLIC_API XXH_errorcode XXH3_freeState | ( | XXH3_state_t * | statePtr | ) |