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