folly/SpookyHashV1.h

   1 /*
   2  * Copyright 2016 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 // This is version 1 of SpookyHash, incompatible with version 2.
  18 //
  19 // SpookyHash: a 128-bit noncryptographic hash function
  20 // By Bob Jenkins, public domain
  21 //   Oct 31 2010: alpha, framework + SpookyHash::Mix appears right
  22 //   Oct 31 2011: alpha again, Mix only good to 2^^69 but rest appears right
  23 //   Dec 31 2011: beta, improved Mix, tested it for 2-bit deltas
  24 //   Feb  2 2012: production, same bits as beta
  25 //   Feb  5 2012: adjusted definitions of uint* to be more portable
  26 //   Mar 30 2012: 3 bytes/cycle, not 4.  Alpha was 4 but wasn't thorough enough.
  27 //
  28 // Up to 3 bytes/cycle for long messages.  Reasonably fast for short messages.
  29 // All 1 or 2 bit deltas achieve avalanche within 1% bias per output bit.
  30 //
  31 // This was developed for and tested on 64-bit x86-compatible processors.
  32 // It assumes the processor is little-endian.  There is a macro
  33 // controlling whether unaligned reads are allowed (by default they are).
  34 // This should be an equally good hash on big-endian machines, but it will
  35 // compute different results on them than on little-endian machines.
  36 //
  37 // Google's CityHash has similar specs to SpookyHash, and CityHash is faster
  38 // on some platforms.  MD4 and MD5 also have similar specs, but they are orders
  39 // of magnitude slower.  CRCs are two or more times slower, but unlike
  40 // SpookyHash, they have nice math for combining the CRCs of pieces to form
  41 // the CRCs of wholes.  There are also cryptographic hashes, but those are even
  42 // slower than MD5.
  43 //
  44
  45 #pragma once
  46
  47 #include <cstddef>
  48 #include <cstdint>
  49
  50 namespace folly {
  51 namespace hash {
  52
  53 class SpookyHashV1
  54 {
  55 public:
  56     //
  57     // SpookyHash: hash a single message in one call, produce 128-bit output
  58     //
  59     static void Hash128(
  60         const void *message,  // message to hash
  61         size_t length,        // length of message in bytes
  62         uint64_t *hash1,      // in/out: in seed 1, out hash value 1
  63         uint64_t *hash2);     // in/out: in seed 2, out hash value 2
  64
  65     //
  66     // Hash64: hash a single message in one call, return 64-bit output
  67     //
  68     static uint64_t Hash64(
  69         const void *message,  // message to hash
  70         size_t length,        // length of message in bytes
  71         uint64_t seed)        // seed
  72     {
  73         uint64_t hash1 = seed;
  74         Hash128(message, length, &hash1, &seed);
  75         return hash1;
  76     }
  77
  78     //
  79     // Hash32: hash a single message in one call, produce 32-bit output
  80     //
  81     static uint32_t Hash32(
  82         const void *message,  // message to hash
  83         size_t length,        // length of message in bytes
  84         uint32_t seed)        // seed
  85     {
  86         uint64_t hash1 = seed, hash2 = seed;
  87         Hash128(message, length, &hash1, &hash2);
  88         return (uint32_t)hash1;
  89     }
  90
  91     //
  92     // Init: initialize the context of a SpookyHash
  93     //
  94     void Init(
  95         uint64_t seed1,     // any 64-bit value will do, including 0
  96         uint64_t seed2);    // different seeds produce independent hashes
  97
  98     //
  99     // Update: add a piece of a message to a SpookyHash state
 100     //
 101     void Update(
 102         const void *message,  // message fragment
 103         size_t length);       // length of message fragment in bytes
 104
 105
 106     //
 107     // Final: compute the hash for the current SpookyHash state
 108     //
 109     // This does not modify the state; you can keep updating it afterward
 110     //
 111     // The result is the same as if SpookyHash() had been called with
 112     // all the pieces concatenated into one message.
 113     //
 114     void Final(
 115         uint64_t *hash1,  // out only: first 64 bits of hash value.
 116         uint64_t *hash2); // out only: second 64 bits of hash value.
 117
 118     //
 119     // left rotate a 64-bit value by k bytes
 120     //
 121     static inline uint64_t Rot64(uint64_t x, int k)
 122     {
 123         return (x << k) | (x >> (64 - k));
 124     }
 125
 126     //
 127     // This is used if the input is 96 bytes long or longer.
 128     //
 129     // The internal state is fully overwritten every 96 bytes.
 130     // Every input bit appears to cause at least 128 bits of entropy
 131     // before 96 other bytes are combined, when run forward or backward
 132     //   For every input bit,
 133     //   Two inputs differing in just that input bit
 134     //   Where "differ" means xor or subtraction
 135     //   And the base value is random
 136     //   When run forward or backwards one Mix
 137     // I tried 3 pairs of each; they all differed by at least 212 bits.
 138     //
 139     static inline void Mix(
 140         const uint64_t *data,
 141         uint64_t &s0, uint64_t &s1, uint64_t &s2, uint64_t &s3,
 142         uint64_t &s4, uint64_t &s5, uint64_t &s6, uint64_t &s7,
 143         uint64_t &s8, uint64_t &s9, uint64_t &s10,uint64_t &s11)
 144     {
 145       s0 += data[0];   s2 ^= s10; s11 ^= s0;  s0 = Rot64(s0,11);   s11 += s1;
 146       s1 += data[1];   s3 ^= s11; s0 ^= s1;   s1 = Rot64(s1,32);   s0 += s2;
 147       s2 += data[2];   s4 ^= s0;  s1 ^= s2;   s2 = Rot64(s2,43);   s1 += s3;
 148       s3 += data[3];   s5 ^= s1;  s2 ^= s3;   s3 = Rot64(s3,31);   s2 += s4;
 149       s4 += data[4];   s6 ^= s2;  s3 ^= s4;   s4 = Rot64(s4,17);   s3 += s5;
 150       s5 += data[5];   s7 ^= s3;  s4 ^= s5;   s5 = Rot64(s5,28);   s4 += s6;
 151       s6 += data[6];   s8 ^= s4;  s5 ^= s6;   s6 = Rot64(s6,39);   s5 += s7;
 152       s7 += data[7];   s9 ^= s5;  s6 ^= s7;   s7 = Rot64(s7,57);   s6 += s8;
 153       s8 += data[8];   s10 ^= s6; s7 ^= s8;   s8 = Rot64(s8,55);   s7 += s9;
 154       s9 += data[9];   s11 ^= s7; s8 ^= s9;   s9 = Rot64(s9,54);   s8 += s10;
 155       s10 += data[10]; s0 ^= s8;  s9 ^= s10;  s10 = Rot64(s10,22); s9 += s11;
 156       s11 += data[11]; s1 ^= s9;  s10 ^= s11; s11 = Rot64(s11,46); s10 += s0;
 157     }
 158
 159     //
 160     // Mix all 12 inputs together so that h0, h1 are a hash of them all.
 161     //
 162     // For two inputs differing in just the input bits
 163     // Where "differ" means xor or subtraction
 164     // And the base value is random, or a counting value starting at that bit
 165     // The final result will have each bit of h0, h1 flip
 166     // For every input bit,
 167     // with probability 50 +- .3%
 168     // For every pair of input bits,
 169     // with probability 50 +- 3%
 170     //
 171     // This does not rely on the last Mix() call having already mixed some.
 172     // Two iterations was almost good enough for a 64-bit result, but a
 173     // 128-bit result is reported, so End() does three iterations.
 174     //
 175     static inline void EndPartial(
 176         uint64_t &h0, uint64_t &h1, uint64_t &h2, uint64_t &h3,
 177         uint64_t &h4, uint64_t &h5, uint64_t &h6, uint64_t &h7,
 178         uint64_t &h8, uint64_t &h9, uint64_t &h10,uint64_t &h11)
 179     {
 180         h11+= h1;    h2 ^= h11;   h1 = Rot64(h1,44);
 181         h0 += h2;    h3 ^= h0;    h2 = Rot64(h2,15);
 182         h1 += h3;    h4 ^= h1;    h3 = Rot64(h3,34);
 183         h2 += h4;    h5 ^= h2;    h4 = Rot64(h4,21);
 184         h3 += h5;    h6 ^= h3;    h5 = Rot64(h5,38);
 185         h4 += h6;    h7 ^= h4;    h6 = Rot64(h6,33);
 186         h5 += h7;    h8 ^= h5;    h7 = Rot64(h7,10);
 187         h6 += h8;    h9 ^= h6;    h8 = Rot64(h8,13);
 188         h7 += h9;    h10^= h7;    h9 = Rot64(h9,38);
 189         h8 += h10;   h11^= h8;    h10= Rot64(h10,53);
 190         h9 += h11;   h0 ^= h9;    h11= Rot64(h11,42);
 191         h10+= h0;    h1 ^= h10;   h0 = Rot64(h0,54);
 192     }
 193
 194     static inline void End(
 195         uint64_t &h0, uint64_t &h1, uint64_t &h2, uint64_t &h3,
 196         uint64_t &h4, uint64_t &h5, uint64_t &h6, uint64_t &h7,
 197         uint64_t &h8, uint64_t &h9, uint64_t &h10,uint64_t &h11)
 198     {
 199         EndPartial(h0,h1,h2,h3,h4,h5,h6,h7,h8,h9,h10,h11);
 200         EndPartial(h0,h1,h2,h3,h4,h5,h6,h7,h8,h9,h10,h11);
 201         EndPartial(h0,h1,h2,h3,h4,h5,h6,h7,h8,h9,h10,h11);
 202     }
 203
 204     //
 205     // The goal is for each bit of the input to expand into 128 bits of
 206     //   apparent entropy before it is fully overwritten.
 207     // n trials both set and cleared at least m bits of h0 h1 h2 h3
 208     //   n: 2   m: 29
 209     //   n: 3   m: 46
 210     //   n: 4   m: 57
 211     //   n: 5   m: 107
 212     //   n: 6   m: 146
 213     //   n: 7   m: 152
 214     // when run forwards or backwards
 215     // for all 1-bit and 2-bit diffs
 216     // with diffs defined by either xor or subtraction
 217     // with a base of all zeros plus a counter, or plus another bit, or random
 218     //
 219     static inline void ShortMix(uint64_t &h0, uint64_t &h1,
 220                                 uint64_t &h2, uint64_t &h3)
 221     {
 222         h2 = Rot64(h2,50);  h2 += h3;  h0 ^= h2;
 223         h3 = Rot64(h3,52);  h3 += h0;  h1 ^= h3;
 224         h0 = Rot64(h0,30);  h0 += h1;  h2 ^= h0;
 225         h1 = Rot64(h1,41);  h1 += h2;  h3 ^= h1;
 226         h2 = Rot64(h2,54);  h2 += h3;  h0 ^= h2;
 227         h3 = Rot64(h3,48);  h3 += h0;  h1 ^= h3;
 228         h0 = Rot64(h0,38);  h0 += h1;  h2 ^= h0;
 229         h1 = Rot64(h1,37);  h1 += h2;  h3 ^= h1;
 230         h2 = Rot64(h2,62);  h2 += h3;  h0 ^= h2;
 231         h3 = Rot64(h3,34);  h3 += h0;  h1 ^= h3;
 232         h0 = Rot64(h0,5);   h0 += h1;  h2 ^= h0;
 233         h1 = Rot64(h1,36);  h1 += h2;  h3 ^= h1;
 234     }
 235
 236     //
 237     // Mix all 4 inputs together so that h0, h1 are a hash of them all.
 238     //
 239     // For two inputs differing in just the input bits
 240     // Where "differ" means xor or subtraction
 241     // And the base value is random, or a counting value starting at that bit
 242     // The final result will have each bit of h0, h1 flip
 243     // For every input bit,
 244     // with probability 50 +- .3% (it is probably better than that)
 245     // For every pair of input bits,
 246     // with probability 50 +- .75% (the worst case is approximately that)
 247     //
 248     static inline void ShortEnd(uint64_t &h0, uint64_t &h1,
 249                                 uint64_t &h2, uint64_t &h3)
 250     {
 251         h3 ^= h2;  h2 = Rot64(h2,15);  h3 += h2;
 252         h0 ^= h3;  h3 = Rot64(h3,52);  h0 += h3;
 253         h1 ^= h0;  h0 = Rot64(h0,26);  h1 += h0;
 254         h2 ^= h1;  h1 = Rot64(h1,51);  h2 += h1;
 255         h3 ^= h2;  h2 = Rot64(h2,28);  h3 += h2;
 256         h0 ^= h3;  h3 = Rot64(h3,9);   h0 += h3;
 257         h1 ^= h0;  h0 = Rot64(h0,47);  h1 += h0;
 258         h2 ^= h1;  h1 = Rot64(h1,54);  h2 += h1;
 259         h3 ^= h2;  h2 = Rot64(h2,32);  h3 += h2;
 260         h0 ^= h3;  h3 = Rot64(h3,25);  h0 += h3;
 261         h1 ^= h0;  h0 = Rot64(h0,63);  h1 += h0;
 262     }
 263
 264 private:
 265
 266     //
 267     // Short is used for messages under 192 bytes in length
 268     // Short has a low startup cost, the normal mode is good for long
 269     // keys, the cost crossover is at about 192 bytes.  The two modes were
 270     // held to the same quality bar.
 271     //
 272     static void Short(
 273         const void *message,  // message (byte array, not necessarily aligned)
 274         size_t length,        // length of message (in bytes)
 275         uint64_t *hash1,      // in/out: in the seed, out the hash value
 276         uint64_t *hash2);     // in/out: in the seed, out the hash value
 277
 278     // number of uint64_t's in internal state
 279     static const size_t sc_numVars = 12;
 280
 281     // size of the internal state
 282     static const size_t sc_blockSize = sc_numVars*8;
 283
 284     // size of buffer of unhashed data, in bytes
 285     static const size_t sc_bufSize = 2*sc_blockSize;
 286
 287     //
 288     // sc_const: a constant which:
 289     //  * is not zero
 290     //  * is odd
 291     //  * is a not-very-regular mix of 1's and 0's
 292     //  * does not need any other special mathematical properties
 293     //
 294     static const uint64_t sc_const = 0xdeadbeefdeadbeefLL;
 295
 296     uint64_t m_data[2*sc_numVars];  // unhashed data, for partial messages
 297     uint64_t m_state[sc_numVars];   // internal state of the hash
 298     size_t m_length;                // total length of the input so far
 299     uint8_t  m_remainder;           // length of unhashed data stashed in m_data
 300 };
 301
 302 }  // namespace hash
 303 }  // namespace folly