folly/Hash.h

   1 /*
   2  * Copyright 2015 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef FOLLY_BASE_HASH_H_
  18 #define FOLLY_BASE_HASH_H_
  19
  20 #include <cstdint>
  21 #include <cstring>
  22 #include <string>
  23 #include <tuple>
  24 #include <type_traits>
  25 #include <utility>
  26
  27 #include <folly/ApplyTuple.h>
  28 #include <folly/Bits.h>
  29 #include <folly/SpookyHashV1.h>
  30 #include <folly/SpookyHashV2.h>
  31
  32 /*
  33  * Various hashing functions.
  34  */
  35
  36 namespace folly { namespace hash {
  37
  38 // This is a general-purpose way to create a single hash from multiple
  39 // hashable objects. hash_combine_generic takes a class Hasher implementing
  40 // hash<T>; hash_combine uses a default hasher StdHasher that uses std::hash.
  41 // hash_combine_generic hashes each argument and combines those hashes in
  42 // an order-dependent way to yield a new hash.
  43
  44
  45 // This is the Hash128to64 function from Google's cityhash (available
  46 // under the MIT License).  We use it to reduce multiple 64 bit hashes
  47 // into a single hash.
  48 inline uint64_t hash_128_to_64(const uint64_t upper, const uint64_t lower) {
  49   // Murmur-inspired hashing.
  50   const uint64_t kMul = 0x9ddfea08eb382d69ULL;
  51   uint64_t a = (lower ^ upper) * kMul;
  52   a ^= (a >> 47);
  53   uint64_t b = (upper ^ a) * kMul;
  54   b ^= (b >> 47);
  55   b *= kMul;
  56   return b;
  57 }
  58
  59 // Never used, but gcc demands it.
  60 template <class Hasher>
  61 inline size_t hash_combine_generic() {
  62   return 0;
  63 }
  64
  65 template <
  66     class Iter,
  67     class Hash = std::hash<typename std::iterator_traits<Iter>::value_type>>
  68 uint64_t hash_range(Iter begin,
  69                     Iter end,
  70                     uint64_t hash = 0,
  71                     Hash hasher = Hash()) {
  72   for (; begin != end; ++begin) {
  73     hash = hash_128_to_64(hash, hasher(*begin));
  74   }
  75   return hash;
  76 }
  77
  78 inline uint32_t twang_32from64(uint64_t key);
  79
  80 template <class Hasher, typename T, typename... Ts>
  81 size_t hash_combine_generic(const T& t, const Ts&... ts) {
  82   size_t seed = Hasher::hash(t);
  83   if (sizeof...(ts) == 0) {
  84     return seed;
  85   }
  86   size_t remainder = hash_combine_generic<Hasher>(ts...);
  87   /* static */ if (sizeof(size_t) == sizeof(uint32_t)) {
  88     return twang_32from64((uint64_t(seed) << 32) | remainder);
  89   } else {
  90     return static_cast<size_t>(hash_128_to_64(seed, remainder));
  91   }
  92 }
  93
  94 // Simply uses std::hash to hash.  Note that std::hash is not guaranteed
  95 // to be a very good hash function; provided std::hash doesn't collide on
  96 // the individual inputs, you are fine, but that won't be true for, say,
  97 // strings or pairs
  98 class StdHasher {
  99  public:
 100   template <typename T>
 101   static size_t hash(const T& t) {
 102     return std::hash<T>()(t);
 103   }
 104 };
 105
 106 template <typename T, typename... Ts>
 107 size_t hash_combine(const T& t, const Ts&... ts) {
 108   return hash_combine_generic<StdHasher>(t, ts...);
 109 }
 110
 111 //////////////////////////////////////////////////////////////////////
 112
 113 /*
 114  * Thomas Wang 64 bit mix hash function
 115  */
 116
 117 inline uint64_t twang_mix64(uint64_t key) {
 118   key = (~key) + (key << 21);  // key *= (1 << 21) - 1; key -= 1;
 119   key = key ^ (key >> 24);
 120   key = key + (key << 3) + (key << 8);  // key *= 1 + (1 << 3) + (1 << 8)
 121   key = key ^ (key >> 14);
 122   key = key + (key << 2) + (key << 4);  // key *= 1 + (1 << 2) + (1 << 4)
 123   key = key ^ (key >> 28);
 124   key = key + (key << 31);  // key *= 1 + (1 << 31)
 125   return key;
 126 }
 127
 128 /*
 129  * Inverse of twang_mix64
 130  *
 131  * Note that twang_unmix64 is significantly slower than twang_mix64.
 132  */
 133
 134 inline uint64_t twang_unmix64(uint64_t key) {
 135   // See the comments in jenkins_rev_unmix32 for an explanation as to how this
 136   // was generated
 137   key *= 4611686016279904257U;
 138   key ^= (key >> 28) ^ (key >> 56);
 139   key *= 14933078535860113213U;
 140   key ^= (key >> 14) ^ (key >> 28) ^ (key >> 42) ^ (key >> 56);
 141   key *= 15244667743933553977U;
 142   key ^= (key >> 24) ^ (key >> 48);
 143   key = (key + 1) * 9223367638806167551U;
 144   return key;
 145 }
 146
 147 /*
 148  * Thomas Wang downscaling hash function
 149  */
 150
 151 inline uint32_t twang_32from64(uint64_t key) {
 152   key = (~key) + (key << 18);
 153   key = key ^ (key >> 31);
 154   key = key * 21;
 155   key = key ^ (key >> 11);
 156   key = key + (key << 6);
 157   key = key ^ (key >> 22);
 158   return (uint32_t) key;
 159 }
 160
 161 /*
 162  * Robert Jenkins' reversible 32 bit mix hash function
 163  */
 164
 165 inline uint32_t jenkins_rev_mix32(uint32_t key) {
 166   key += (key << 12);  // key *= (1 + (1 << 12))
 167   key ^= (key >> 22);
 168   key += (key << 4);   // key *= (1 + (1 << 4))
 169   key ^= (key >> 9);
 170   key += (key << 10);  // key *= (1 + (1 << 10))
 171   key ^= (key >> 2);
 172   // key *= (1 + (1 << 7)) * (1 + (1 << 12))
 173   key += (key << 7);
 174   key += (key << 12);
 175   return key;
 176 }
 177
 178 /*
 179  * Inverse of jenkins_rev_mix32
 180  *
 181  * Note that jenkinks_rev_unmix32 is significantly slower than
 182  * jenkins_rev_mix32.
 183  */
 184
 185 inline uint32_t jenkins_rev_unmix32(uint32_t key) {
 186   // These are the modular multiplicative inverses (in Z_2^32) of the
 187   // multiplication factors in jenkins_rev_mix32, in reverse order.  They were
 188   // computed using the Extended Euclidean algorithm, see
 189   // http://en.wikipedia.org/wiki/Modular_multiplicative_inverse
 190   key *= 2364026753U;
 191
 192   // The inverse of a ^= (a >> n) is
 193   // b = a
 194   // for (int i = n; i < 32; i += n) {
 195   //   b ^= (a >> i);
 196   // }
 197   key ^=
 198     (key >> 2) ^ (key >> 4) ^ (key >> 6) ^ (key >> 8) ^
 199     (key >> 10) ^ (key >> 12) ^ (key >> 14) ^ (key >> 16) ^
 200     (key >> 18) ^ (key >> 20) ^ (key >> 22) ^ (key >> 24) ^
 201     (key >> 26) ^ (key >> 28) ^ (key >> 30);
 202   key *= 3222273025U;
 203   key ^= (key >> 9) ^ (key >> 18) ^ (key >> 27);
 204   key *= 4042322161U;
 205   key ^= (key >> 22);
 206   key *= 16773121U;
 207   return key;
 208 }
 209
 210 /*
 211  * Fowler / Noll / Vo (FNV) Hash
 212  *     http://www.isthe.com/chongo/tech/comp/fnv/
 213  */
 214
 215 const uint32_t FNV_32_HASH_START = 2166136261UL;
 216 const uint64_t FNV_64_HASH_START = 14695981039346656037ULL;
 217
 218 inline uint32_t fnv32(const char* s,
 219                       uint32_t hash = FNV_32_HASH_START) {
 220   for (; *s; ++s) {
 221     hash += (hash << 1) + (hash << 4) + (hash << 7) +
 222             (hash << 8) + (hash << 24);
 223     hash ^= *s;
 224   }
 225   return hash;
 226 }
 227
 228 inline uint32_t fnv32_buf(const void* buf,
 229                           size_t n,
 230                           uint32_t hash = FNV_32_HASH_START) {
 231   // forcing signed char, since other platforms can use unsigned
 232   const signed char* char_buf = reinterpret_cast<const signed char*>(buf);
 233
 234   for (size_t i = 0; i < n; ++i) {
 235     hash += (hash << 1) + (hash << 4) + (hash << 7) +
 236             (hash << 8) + (hash << 24);
 237     hash ^= char_buf[i];
 238   }
 239
 240   return hash;
 241 }
 242
 243 inline uint32_t fnv32(const std::string& str,
 244                       uint32_t hash = FNV_32_HASH_START) {
 245   return fnv32_buf(str.data(), str.size(), hash);
 246 }
 247
 248 inline uint64_t fnv64(const char* s,
 249                       uint64_t hash = FNV_64_HASH_START) {
 250   for (; *s; ++s) {
 251     hash += (hash << 1) + (hash << 4) + (hash << 5) + (hash << 7) +
 252       (hash << 8) + (hash << 40);
 253     hash ^= *s;
 254   }
 255   return hash;
 256 }
 257
 258 inline uint64_t fnv64_buf(const void* buf,
 259                           size_t n,
 260                           uint64_t hash = FNV_64_HASH_START) {
 261   // forcing signed char, since other platforms can use unsigned
 262   const signed char* char_buf = reinterpret_cast<const signed char*>(buf);
 263
 264   for (size_t i = 0; i < n; ++i) {
 265     hash += (hash << 1) + (hash << 4) + (hash << 5) + (hash << 7) +
 266       (hash << 8) + (hash << 40);
 267     hash ^= char_buf[i];
 268   }
 269   return hash;
 270 }
 271
 272 inline uint64_t fnv64(const std::string& str,
 273                       uint64_t hash = FNV_64_HASH_START) {
 274   return fnv64_buf(str.data(), str.size(), hash);
 275 }
 276
 277 /*
 278  * Paul Hsieh: http://www.azillionmonkeys.com/qed/hash.html
 279  */
 280
 281 #define get16bits(d) folly::loadUnaligned<uint16_t>(d)
 282
 283 inline uint32_t hsieh_hash32_buf(const void* buf, size_t len) {
 284   // forcing signed char, since other platforms can use unsigned
 285   const signed char* s = reinterpret_cast<const signed char*>(buf);
 286   uint32_t hash = static_cast<uint32_t>(len);
 287   uint32_t tmp;
 288   size_t rem;
 289
 290   if (len <= 0 || buf == 0) {
 291     return 0;
 292   }
 293
 294   rem = len & 3;
 295   len >>= 2;
 296
 297   /* Main loop */
 298   for (;len > 0; len--) {
 299     hash  += get16bits (s);
 300     tmp    = (get16bits (s+2) << 11) ^ hash;
 301     hash   = (hash << 16) ^ tmp;
 302     s  += 2*sizeof (uint16_t);
 303     hash  += hash >> 11;
 304   }
 305
 306   /* Handle end cases */
 307   switch (rem) {
 308   case 3:
 309     hash += get16bits(s);
 310     hash ^= hash << 16;
 311     hash ^= s[sizeof (uint16_t)] << 18;
 312     hash += hash >> 11;
 313     break;
 314   case 2:
 315     hash += get16bits(s);
 316     hash ^= hash << 11;
 317     hash += hash >> 17;
 318     break;
 319   case 1:
 320     hash += *s;
 321     hash ^= hash << 10;
 322     hash += hash >> 1;
 323   }
 324
 325   /* Force "avalanching" of final 127 bits */
 326   hash ^= hash << 3;
 327   hash += hash >> 5;
 328   hash ^= hash << 4;
 329   hash += hash >> 17;
 330   hash ^= hash << 25;
 331   hash += hash >> 6;
 332
 333   return hash;
 334 };
 335
 336 #undef get16bits
 337
 338 inline uint32_t hsieh_hash32(const char* s) {
 339   return hsieh_hash32_buf(s, std::strlen(s));
 340 }
 341
 342 inline uint32_t hsieh_hash32_str(const std::string& str) {
 343   return hsieh_hash32_buf(str.data(), str.size());
 344 }
 345
 346 //////////////////////////////////////////////////////////////////////
 347
 348 } // namespace hash
 349
 350 template<class Key, class Enable = void>
 351 struct hasher;
 352
 353 struct Hash {
 354   template <class T>
 355   size_t operator()(const T& v) const {
 356     return hasher<T>()(v);
 357   }
 358
 359   template <class T, class... Ts>
 360   size_t operator()(const T& t, const Ts&... ts) const {
 361     return hash::hash_128_to_64((*this)(t), (*this)(ts...));
 362   }
 363 };
 364
 365 template<> struct hasher<int32_t> {
 366   size_t operator()(int32_t key) const {
 367     return hash::jenkins_rev_mix32(uint32_t(key));
 368   }
 369 };
 370
 371 template<> struct hasher<uint32_t> {
 372   size_t operator()(uint32_t key) const {
 373     return hash::jenkins_rev_mix32(key);
 374   }
 375 };
 376
 377 template<> struct hasher<int64_t> {
 378   size_t operator()(int64_t key) const {
 379     return static_cast<size_t>(hash::twang_mix64(uint64_t(key)));
 380   }
 381 };
 382
 383 template<> struct hasher<uint64_t> {
 384   size_t operator()(uint64_t key) const {
 385     return static_cast<size_t>(hash::twang_mix64(key));
 386   }
 387 };
 388
 389 template<> struct hasher<std::string> {
 390   size_t operator()(const std::string& key) const {
 391     return static_cast<size_t>(
 392         hash::SpookyHashV2::Hash64(key.data(), key.size(), 0));
 393   }
 394 };
 395
 396 template <class T>
 397 struct hasher<T, typename std::enable_if<std::is_enum<T>::value, void>::type> {
 398   size_t operator()(T key) const {
 399     return Hash()(static_cast<typename std::underlying_type<T>::type>(key));
 400   }
 401 };
 402
 403 template <class T1, class T2>
 404 struct hasher<std::pair<T1, T2>> {
 405   size_t operator()(const std::pair<T1, T2>& key) const {
 406     return Hash()(key.first, key.second);
 407   }
 408 };
 409
 410 template <typename... Ts>
 411 struct hasher<std::tuple<Ts...>> {
 412   size_t operator() (const std::tuple<Ts...>& key) const {
 413     return applyTuple(Hash(), key);
 414   }
 415 };
 416
 417 // recursion
 418 template <size_t index, typename... Ts>
 419 struct TupleHasher {
 420   size_t operator()(std::tuple<Ts...> const& key) const {
 421     return hash::hash_combine(
 422       TupleHasher<index - 1, Ts...>()(key),
 423       std::get<index>(key));
 424   }
 425 };
 426
 427 // base
 428 template <typename... Ts>
 429 struct TupleHasher<0, Ts...> {
 430   size_t operator()(std::tuple<Ts...> const& key) const {
 431     // we could do std::hash here directly, but hash_combine hides all the
 432     // ugly templating implicitly
 433     return hash::hash_combine(std::get<0>(key));
 434   }
 435 };
 436
 437 } // namespace folly
 438
 439 // Custom hash functions.
 440 namespace std {
 441   // Hash function for pairs. Requires default hash functions for both
 442   // items in the pair.
 443   template <typename T1, typename T2>
 444   struct hash<std::pair<T1, T2> > {
 445   public:
 446     size_t operator()(const std::pair<T1, T2>& x) const {
 447       return folly::hash::hash_combine(x.first, x.second);
 448     }
 449   };
 450
 451   // Hash function for tuples. Requires default hash functions for all types.
 452   template <typename... Ts>
 453   struct hash<std::tuple<Ts...>> {
 454     size_t operator()(std::tuple<Ts...> const& key) const {
 455       folly::TupleHasher<
 456         std::tuple_size<std::tuple<Ts...>>::value - 1, // start index
 457         Ts...> hasher;
 458
 459       return hasher(key);
 460     }
 461   };
 462 } // namespace std
 463
 464 #endif