1 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0-only 2 /* 3 * xxHash - Extremely Fast Hash algorithm 4 * Header File 5 * Copyright (c) 2012-2020, Yann Collet, Facebook, Inc. 6 * 7 * You can contact the author at : 8 * - xxHash source repository : https://github.com/Cyan4973/xxHash 9 * 10 * This source code is licensed under both the BSD-style license (found in the 11 * LICENSE file in the root directory of this source tree) and the GPLv2 (found 12 * in the COPYING file in the root directory of this source tree). 13 * You may select, at your option, one of the above-listed licenses. 14 */ 15 16 /* Notice extracted from xxHash homepage : 17 18 xxHash is an extremely fast Hash algorithm, running at RAM speed limits. 19 It also successfully passes all tests from the SMHasher suite. 20 21 Comparison (single thread, Windows Seven 32 bits, using SMHasher on a Core 2 Duo @3GHz) 22 23 Name Speed Q.Score Author 24 xxHash 5.4 GB/s 10 25 CrapWow 3.2 GB/s 2 Andrew 26 MumurHash 3a 2.7 GB/s 10 Austin Appleby 27 SpookyHash 2.0 GB/s 10 Bob Jenkins 28 SBox 1.4 GB/s 9 Bret Mulvey 29 Lookup3 1.2 GB/s 9 Bob Jenkins 30 SuperFastHash 1.2 GB/s 1 Paul Hsieh 31 CityHash64 1.05 GB/s 10 Pike & Alakuijala 32 FNV 0.55 GB/s 5 Fowler, Noll, Vo 33 CRC32 0.43 GB/s 9 34 MD5-32 0.33 GB/s 10 Ronald L. Rivest 35 SHA1-32 0.28 GB/s 10 36 37 Q.Score is a measure of quality of the hash function. 38 It depends on successfully passing SMHasher test set. 39 10 is a perfect score. 40 41 A 64-bits version, named XXH64, is available since r35. 42 It offers much better speed, but for 64-bits applications only. 43 Name Speed on 64 bits Speed on 32 bits 44 XXH64 13.8 GB/s 1.9 GB/s 45 XXH32 6.8 GB/s 6.0 GB/s 46 */ 47 48 #if defined (__cplusplus) 49 extern "C" { 50 #endif 51 52 #ifndef XXHASH_H_5627135585666179 53 #define XXHASH_H_5627135585666179 1 54 55 56 /* **************************** 57 * Definitions 58 ******************************/ 59 #include <stddef.h> /* size_t */ 60 typedef enum { XXH_OK=0, XXH_ERROR } XXH_errorcode; 61 62 63 /* **************************** 64 * API modifier 65 ******************************/ 66 /** XXH_PRIVATE_API 67 * This is useful if you want to include xxhash functions in `static` mode 68 * in order to inline them, and remove their symbol from the public list. 69 * Methodology : 70 * #define XXH_PRIVATE_API 71 * #include "xxhash.h" 72 * `xxhash.c` is automatically included. 73 * It's not useful to compile and link it as a separate module anymore. 74 */ 75 #ifdef XXH_PRIVATE_API 76 # ifndef XXH_STATIC_LINKING_ONLY 77 # define XXH_STATIC_LINKING_ONLY 78 # endif 79 # if defined(__GNUC__) 80 # define XXH_PUBLIC_API static __inline __attribute__((unused)) 81 # elif defined (__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */) 82 # define XXH_PUBLIC_API static inline 83 # elif defined(_MSC_VER) 84 # define XXH_PUBLIC_API static __inline 85 # else 86 # define XXH_PUBLIC_API static /* this version may generate warnings for unused static functions; disable the relevant warning */ 87 # endif 88 #else 89 # define XXH_PUBLIC_API /* do nothing */ 90 #endif /* XXH_PRIVATE_API */ 91 92 /*!XXH_NAMESPACE, aka Namespace Emulation : 93 94 If you want to include _and expose_ xxHash functions from within your own library, 95 but also want to avoid symbol collisions with another library which also includes xxHash, 96 97 you can use XXH_NAMESPACE, to automatically prefix any public symbol from xxhash library 98 with the value of XXH_NAMESPACE (so avoid to keep it NULL and avoid numeric values). 99 100 Note that no change is required within the calling program as long as it includes `xxhash.h` : 101 regular symbol name will be automatically translated by this header. 102 */ 103 #ifdef XXH_NAMESPACE 104 # define XXH_CAT(A,B) A##B 105 # define XXH_NAME2(A,B) XXH_CAT(A,B) 106 # define XXH32 XXH_NAME2(XXH_NAMESPACE, XXH32) 107 # define XXH64 XXH_NAME2(XXH_NAMESPACE, XXH64) 108 # define XXH_versionNumber XXH_NAME2(XXH_NAMESPACE, XXH_versionNumber) 109 # define XXH32_createState XXH_NAME2(XXH_NAMESPACE, XXH32_createState) 110 # define XXH64_createState XXH_NAME2(XXH_NAMESPACE, XXH64_createState) 111 # define XXH32_freeState XXH_NAME2(XXH_NAMESPACE, XXH32_freeState) 112 # define XXH64_freeState XXH_NAME2(XXH_NAMESPACE, XXH64_freeState) 113 # define XXH32_reset XXH_NAME2(XXH_NAMESPACE, XXH32_reset) 114 # define XXH64_reset XXH_NAME2(XXH_NAMESPACE, XXH64_reset) 115 # define XXH32_update XXH_NAME2(XXH_NAMESPACE, XXH32_update) 116 # define XXH64_update XXH_NAME2(XXH_NAMESPACE, XXH64_update) 117 # define XXH32_digest XXH_NAME2(XXH_NAMESPACE, XXH32_digest) 118 # define XXH64_digest XXH_NAME2(XXH_NAMESPACE, XXH64_digest) 119 # define XXH32_copyState XXH_NAME2(XXH_NAMESPACE, XXH32_copyState) 120 # define XXH64_copyState XXH_NAME2(XXH_NAMESPACE, XXH64_copyState) 121 # define XXH32_canonicalFromHash XXH_NAME2(XXH_NAMESPACE, XXH32_canonicalFromHash) 122 # define XXH64_canonicalFromHash XXH_NAME2(XXH_NAMESPACE, XXH64_canonicalFromHash) 123 # define XXH32_hashFromCanonical XXH_NAME2(XXH_NAMESPACE, XXH32_hashFromCanonical) 124 # define XXH64_hashFromCanonical XXH_NAME2(XXH_NAMESPACE, XXH64_hashFromCanonical) 125 #endif 126 127 128 /* ************************************* 129 * Version 130 ***************************************/ 131 #define XXH_VERSION_MAJOR 0 132 #define XXH_VERSION_MINOR 6 133 #define XXH_VERSION_RELEASE 2 134 #define XXH_VERSION_NUMBER (XXH_VERSION_MAJOR *100*100 + XXH_VERSION_MINOR *100 + XXH_VERSION_RELEASE) 135 XXH_PUBLIC_API unsigned XXH_versionNumber (void); 136 137 138 /* **************************** 139 * Simple Hash Functions 140 ******************************/ 141 typedef unsigned int XXH32_hash_t; 142 typedef unsigned long long XXH64_hash_t; 143 144 XXH_PUBLIC_API XXH32_hash_t XXH32 (const void* input, size_t length, unsigned int seed); 145 XXH_PUBLIC_API XXH64_hash_t XXH64 (const void* input, size_t length, unsigned long long seed); 146 147 /*! 148 XXH32() : 149 Calculate the 32-bits hash of sequence "length" bytes stored at memory address "input". 150 The memory between input & input+length must be valid (allocated and read-accessible). 151 "seed" can be used to alter the result predictably. 152 Speed on Core 2 Duo @ 3 GHz (single thread, SMHasher benchmark) : 5.4 GB/s 153 XXH64() : 154 Calculate the 64-bits hash of sequence of length "len" stored at memory address "input". 155 "seed" can be used to alter the result predictably. 156 This function runs 2x faster on 64-bits systems, but slower on 32-bits systems (see benchmark). 157 */ 158 159 160 /* **************************** 161 * Streaming Hash Functions 162 ******************************/ 163 typedef struct XXH32_state_s XXH32_state_t; /* incomplete type */ 164 typedef struct XXH64_state_s XXH64_state_t; /* incomplete type */ 165 166 /*! State allocation, compatible with dynamic libraries */ 167 168 XXH_PUBLIC_API XXH32_state_t* XXH32_createState(void); 169 XXH_PUBLIC_API XXH_errorcode XXH32_freeState(XXH32_state_t* statePtr); 170 171 XXH_PUBLIC_API XXH64_state_t* XXH64_createState(void); 172 XXH_PUBLIC_API XXH_errorcode XXH64_freeState(XXH64_state_t* statePtr); 173 174 175 /* hash streaming */ 176 177 XXH_PUBLIC_API XXH_errorcode XXH32_reset (XXH32_state_t* statePtr, unsigned int seed); 178 XXH_PUBLIC_API XXH_errorcode XXH32_update (XXH32_state_t* statePtr, const void* input, size_t length); 179 XXH_PUBLIC_API XXH32_hash_t XXH32_digest (const XXH32_state_t* statePtr); 180 181 XXH_PUBLIC_API XXH_errorcode XXH64_reset (XXH64_state_t* statePtr, unsigned long long seed); 182 XXH_PUBLIC_API XXH_errorcode XXH64_update (XXH64_state_t* statePtr, const void* input, size_t length); 183 XXH_PUBLIC_API XXH64_hash_t XXH64_digest (const XXH64_state_t* statePtr); 184 185 /* 186 These functions generate the xxHash of an input provided in multiple segments. 187 Note that, for small input, they are slower than single-call functions, due to state management. 188 For small input, prefer `XXH32()` and `XXH64()` . 189 190 XXH state must first be allocated, using XXH*_createState() . 191 192 Start a new hash by initializing state with a seed, using XXH*_reset(). 193 194 Then, feed the hash state by calling XXH*_update() as many times as necessary. 195 Obviously, input must be allocated and read accessible. 196 The function returns an error code, with 0 meaning OK, and any other value meaning there is an error. 197 198 Finally, a hash value can be produced anytime, by using XXH*_digest(). 199 This function returns the nn-bits hash as an int or long long. 200 201 It's still possible to continue inserting input into the hash state after a digest, 202 and generate some new hashes later on, by calling again XXH*_digest(). 203 204 When done, free XXH state space if it was allocated dynamically. 205 */ 206 207 208 /* ************************** 209 * Utils 210 ****************************/ 211 #if !(defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)) /* ! C99 */ 212 # define restrict /* disable restrict */ 213 #endif 214 215 XXH_PUBLIC_API void XXH32_copyState(XXH32_state_t* restrict dst_state, const XXH32_state_t* restrict src_state); 216 XXH_PUBLIC_API void XXH64_copyState(XXH64_state_t* restrict dst_state, const XXH64_state_t* restrict src_state); 217 218 219 /* ************************** 220 * Canonical representation 221 ****************************/ 222 /* Default result type for XXH functions are primitive unsigned 32 and 64 bits. 223 * The canonical representation uses human-readable write convention, aka big-endian (large digits first). 224 * These functions allow transformation of hash result into and from its canonical format. 225 * This way, hash values can be written into a file / memory, and remain comparable on different systems and programs. 226 */ 227 typedef struct { unsigned char digest[4]; } XXH32_canonical_t; 228 typedef struct { unsigned char digest[8]; } XXH64_canonical_t; 229 230 XXH_PUBLIC_API void XXH32_canonicalFromHash(XXH32_canonical_t* dst, XXH32_hash_t hash); 231 XXH_PUBLIC_API void XXH64_canonicalFromHash(XXH64_canonical_t* dst, XXH64_hash_t hash); 232 233 XXH_PUBLIC_API XXH32_hash_t XXH32_hashFromCanonical(const XXH32_canonical_t* src); 234 XXH_PUBLIC_API XXH64_hash_t XXH64_hashFromCanonical(const XXH64_canonical_t* src); 235 236 #endif /* XXHASH_H_5627135585666179 */ 237 238 239 240 /* ================================================================================================ 241 This section contains definitions which are not guaranteed to remain stable. 242 They may change in future versions, becoming incompatible with a different version of the library. 243 They shall only be used with static linking. 244 Never use these definitions in association with dynamic linking ! 245 =================================================================================================== */ 246 #if defined(XXH_STATIC_LINKING_ONLY) && !defined(XXH_STATIC_H_3543687687345) 247 #define XXH_STATIC_H_3543687687345 248 249 /* These definitions are only meant to allow allocation of XXH state 250 statically, on stack, or in a struct for example. 251 Do not use members directly. */ 252 253 struct XXH32_state_s { 254 unsigned total_len_32; 255 unsigned large_len; 256 unsigned v1; 257 unsigned v2; 258 unsigned v3; 259 unsigned v4; 260 unsigned mem32[4]; /* buffer defined as U32 for alignment */ 261 unsigned memsize; 262 unsigned reserved; /* never read nor write, will be removed in a future version */ 263 }; /* typedef'd to XXH32_state_t */ 264 265 struct XXH64_state_s { 266 unsigned long long total_len; 267 unsigned long long v1; 268 unsigned long long v2; 269 unsigned long long v3; 270 unsigned long long v4; 271 unsigned long long mem64[4]; /* buffer defined as U64 for alignment */ 272 unsigned memsize; 273 unsigned reserved[2]; /* never read nor write, will be removed in a future version */ 274 }; /* typedef'd to XXH64_state_t */ 275 276 277 # ifdef XXH_PRIVATE_API 278 # include "xxhash.c" /* include xxhash functions as `static`, for inlining */ 279 # endif 280 281 #endif /* XXH_STATIC_LINKING_ONLY && XXH_STATIC_H_3543687687345 */ 282 283 284 #if defined (__cplusplus) 285 } 286 #endif 287