Initial commit
[nbds] / struct / ht.c
1 /* 
2  * Written by Josh Dybnis and released to the public domain, as explained at
3  * http://creativecommons.org/licenses/publicdomain
4  * 
5  * C implementation of Cliff Click's lock-free hash table from 
6  * http://www.azulsystems.com/events/javaone_2008/2008_CodingNonBlock.pdf
7  * http://sourceforge.net/projects/high-scale-lib
8  *
9  * Note: This is code uses synchronous atomic operations because that is all that x86 provides. 
10  * Every atomic operation is also an implicit full memory barrier. The upshot is that it simplifies
11  * the code a bit, but it won't be as fast as it could be on platforms like SPARC that provide 
12  * weaker operations which would still do the job.
13  */
14
15 #include "common.h"
16 #include "ht.h"
17 #include "murmur.h"
18 #include "mem.h"
19 #include "rcu.h"
20
21 #define COPIED_VALUE            (-1)
22 #define TOMBSTONE               STRIP_TAG(COPIED_VALUE)
23
24 #define ENTRIES_PER_BUCKET      (CACHE_LINE_SIZE/sizeof(entry_t))
25 #define ENTRIES_PER_COPY_CHUNK  (ENTRIES_PER_BUCKET * 2)
26 #define MIN_SCALE               (__builtin_ctz(ENTRIES_PER_BUCKET) + 2) // min 4 buckets
27 #define MAX_BUCKETS_TO_PROBE    250
28
29 typedef struct ht_entry {
30     int64_t key;
31     int64_t value;
32 } entry_t;
33
34 typedef struct string {
35     uint32_t len;
36     char val[];
37 } string_t;
38
39 typedef struct hash_table_i {
40     volatile entry_t *table;
41     hash_table_t *ht; // parent ht;
42     struct hash_table_i *next;
43     struct hash_table_i *next_free;
44     unsigned int scale;
45     int max_probe;
46     int count; // TODO: make these counters distributed
47     int num_entries_copied;
48     int scan;
49 } hash_table_i_t;
50
51 static int hti_copy_entry 
52     (hash_table_i_t *old_hti, volatile entry_t *e, uint32_t e_key_hash, hash_table_i_t *new_hti);
53
54 // Choose the next bucket to probe using the high-order bits of <key_hash>.
55 static inline int get_next_ndx(int old_ndx, uint32_t key_hash, int ht_scale) {
56     int incr = (key_hash >> (32 - ht_scale));
57     incr += !incr; // If the increment is 0, make it 1.
58     return (old_ndx + incr) & MASK(ht_scale);
59 }
60
61 // Compare two keys.
62 //
63 // A key is made up of two parts. The 48 low-order bits are a pointer to a null terminated string.
64 // The high-order 16 bits are taken from the hash of that string. The bits from the hash are used 
65 // as a quick check to rule out non-equal keys without doing a complete string compare.
66 static inline int ht_key_equals (uint64_t a, uint32_t b_hash, const char *b_value, uint32_t b_len) {
67     if ((b_hash >> 16) != (a >> 48)) // high-order 16 bits are from the hash value
68         return FALSE;
69     const string_t *a_key = (string_t *)(a & MASK(48)); // low-order 48 bits is a pointer 
70     assert(a_key);
71     return a_key->len == b_len && memcmp(a_key->val, b_value, b_len) == 0;
72 }
73
74 // Lookup <key> in <hti>. 
75 //
76 // Return the entry that <key> is in, or if <key> isn't in <hti> return the entry that it would be 
77 // in if it were inserted into <hti>. If there is no room for <key> in <hti> then return NULL, to 
78 // indicate that the caller should look in <hti->next>.
79 //
80 // Record if the entry being returned is empty. Otherwise the caller will have to waste time with
81 // ht_key_equals() to confirm that it did not lose a race to fill an empty entry.
82 static volatile entry_t *hti_lookup (hash_table_i_t *hti, uint32_t key_hash, const char *key_val, uint32_t key_len, int *is_empty) {
83     TRACE("h0", "hti_lookup(key \"%s\" in hti %p)", key_val, hti);
84     *is_empty = 0;
85
86     // Probe one cache line at a time
87     int ndx = key_hash & MASK(hti->scale); // the first entry to search
88     int i;
89     for (i = 0; i < hti->max_probe; ++i) {
90
91         // The start of the bucket is the first entry in the cache line.
92         volatile entry_t *bucket = hti->table + (ndx & ~(ENTRIES_PER_BUCKET-1)); 
93
94         // Start searching at the indexed entry. Then loop around to the begining of the cache line.
95         int j;
96         for (j = 0; j < ENTRIES_PER_BUCKET; ++j) {
97             volatile entry_t *e = bucket + ((ndx + j) & (ENTRIES_PER_BUCKET-1));
98
99             uint64_t e_key = e->key;
100             if (e_key == DOES_NOT_EXIST) {
101                 TRACE("h0", "hti_lookup: empty entry %p found on probe %d", e, i*ENTRIES_PER_BUCKET+j+1);
102                 // we tag the pointer so the caller can avoid an expensive ht_key_equals()
103                 *is_empty = 1;
104                 return e;
105             }
106
107             if (ht_key_equals(e_key, key_hash, key_val, key_len)) {
108                 TRACE("h0", "hti_lookup: entry %p found on probe %d", e, i*ENTRIES_PER_BUCKET+j+1);
109                 TRACE("h0", "hti_lookup: with key \"%s\" value %p", 
110                             ((string_t *)(e_key & MASK(48)))->val, e->value);
111                 return e;
112             }
113         }
114
115         ndx = get_next_ndx(ndx, key_hash, hti->scale);
116     }
117
118     // maximum number of probes exceeded
119     TRACE("h0", "hti_lookup: maximum number of probes exceeded returning 0x0", 0, 0);
120     return NULL;
121 }
122
123 // Allocate and initialize a hash_table_i_t with 2^<scale> entries.
124 static hash_table_i_t *hti_alloc (hash_table_t *parent, int scale) {
125     // Include enough slop to align the actual table on a cache line boundry
126     size_t n = sizeof(hash_table_i_t) 
127              + sizeof(entry_t) * (1 << scale) 
128              + (CACHE_LINE_SIZE - 1);
129     hash_table_i_t *hti = (hash_table_i_t *)calloc(n, 1);
130
131     // Align the table of hash entries on a cache line boundry.
132     hti->table = (entry_t *)(((uint64_t)hti + sizeof(hash_table_i_t) + (CACHE_LINE_SIZE-1)) 
133                             & ~(CACHE_LINE_SIZE-1));
134
135     hti->scale = scale;
136
137     // When searching for a key probe a maximum of 1/4 of the buckets up to 1000 buckets.
138     hti->max_probe = ((1 << (hti->scale - 2)) / ENTRIES_PER_BUCKET) + 2;
139     if (hti->max_probe > MAX_BUCKETS_TO_PROBE) {
140         hti->max_probe = MAX_BUCKETS_TO_PROBE;
141     }
142
143     hti->ht = parent;
144
145     assert(hti->scale >= MIN_SCALE && hti->scale < 63); // size must be a power of 2
146     assert(sizeof(entry_t) * ENTRIES_PER_BUCKET % CACHE_LINE_SIZE == 0); // divisible into cache
147     assert((size_t)hti->table % CACHE_LINE_SIZE == 0); // cache aligned
148
149     return hti;
150 }
151
152 // Called when <hti> runs out of room for new keys.
153 //
154 // Initiates a copy by creating a larger hash_table_i_t and installing it in <hti->next>.
155 static void hti_start_copy (hash_table_i_t *hti) {
156     TRACE("h0", "hti_start_copy(hti %p hti->next %p)", hti, hti->next);
157     if (hti->next) 
158         return; // another thread beat us to it
159
160     // heuristics to determine the size of the new table
161     uint64_t count = ht_count(hti->ht);
162     unsigned int new_scale = hti->scale;
163     new_scale += (count > (1 << (new_scale - 2))); // double size if more than 1/4 full
164     new_scale += (count > (1 << (new_scale - 2))); // double size again if more than 1/2 full
165
166     // Allocate the new table and attempt to install it.
167     hash_table_i_t *next = hti_alloc(hti->ht, hti->scale + 1);
168     hash_table_i_t *old_next = SYNC_CAS(&hti->next, NULL, next);
169     if (old_next != NULL) {
170         TRACE("h0", "hti_start_copy: lost race to install new hti; found %p", old_next, 0);
171         // Another thread beat us to it.
172         nbd_free(next);
173         return;
174     }
175     TRACE("h0", "hti_start_copy: new hti is %p", next, 0);
176 }
177
178 // Copy the key and value stored in <old_e> (which must be an entry in <old_hti>) to <new_hti>. 
179 //
180 // Return 1 unless <old_e> is already copied (then return 0), so the caller can account for the total
181 // number of entries left to copy.
182 static int hti_copy_entry (hash_table_i_t *old_hti, volatile entry_t *old_e, uint32_t key_hash, 
183                            hash_table_i_t *new_hti) {
184     TRACE("h0", "hti_copy_entry(copy entry from %p to %p)", old_hti, new_hti);
185     assert(old_hti);
186     assert(old_hti->next);
187     assert(new_hti);
188     assert(old_e >= old_hti->table && old_e < old_hti->table + (1 << old_hti->scale));
189
190     int64_t old_e_value = old_e->value;
191     TRACE("h0", "hti_copy_entry: entry %p current value %p", old_e, old_e_value);
192     if (EXPECT_FALSE(old_e_value == COPIED_VALUE))
193         return FALSE; // already copied
194
195     // Kill empty entries.
196     if (EXPECT_FALSE(old_e_value == DOES_NOT_EXIST)) {
197         old_e_value = SYNC_CAS(&old_e->value, DOES_NOT_EXIST, COPIED_VALUE);
198         if (old_e_value == DOES_NOT_EXIST) {
199             TRACE("h0", "hti_copy_entry: old entry killed", 0, 0);
200             return TRUE;
201         }
202         if (old_e_value == COPIED_VALUE) {
203             TRACE("h0", "hti_copy_entry: lost race to kill empty entry in old hti", 0, 0);
204             return FALSE; // another thread beat us to it
205         }
206         TRACE("h0", "hti_copy_entry: lost race to kill empty entry in old hti; "
207                     "the entry is now being used", 0, 0);
208     }
209
210     // Tag the value in the old entry to indicate a copy is in progress.
211     old_e_value = SYNC_FETCH_AND_OR(&old_e->value, TAG_VALUE(0));
212     TRACE("h0", "hti_copy_entry: tagged the value %p in old entry %p", old_e_value, old_e);
213     if (old_e_value == COPIED_VALUE) 
214         return FALSE; // <value> was already copied by another thread.
215
216     // Deleted entries don't need to be installed into to the new table, but their keys do need to
217     // be freed.
218     assert(COPIED_VALUE == TAG_VALUE(TOMBSTONE));
219     if (old_e_value == TOMBSTONE) {
220         nbd_free((string_t *)(old_e->key & MASK(48)));
221         return TRUE; 
222     }
223     old_e_value = STRIP_TAG(old_e_value);
224
225     // Install the key in the new table.
226     uint64_t old_e_key = old_e->key;
227     string_t *key = (string_t *)(old_e_key & MASK(48));
228     TRACE("h0", "hti_copy_entry: key %p is %s", old_e_key, key->val);
229
230     // We use 0 to indicate that <key_hash> isn't initiallized. Occasionally the <key_hash> will
231     // really be 0 and we will waste time recomputing it. That is rare enough that it is OK. 
232     if (key_hash == 0) { 
233         key_hash = murmur32(key->val, key->len);
234     }
235
236     int is_empty;
237     volatile entry_t *new_e = hti_lookup(new_hti, key_hash, key->val, key->len, &is_empty);
238
239     // it is possible that there is not any room in the new table either
240     if (EXPECT_FALSE(new_e == NULL)) {
241         hti_start_copy(new_hti); // initiate nested copy, if not already started
242         return hti_copy_entry(old_hti, old_e, key_hash, new_hti->next); // recursive tail-call
243     }
244
245     // a tagged entry returned from hti_lookup() means it is either empty or has a new key
246     if (is_empty) {
247         uint64_t new_e_key = SYNC_CAS(&new_e->key, DOES_NOT_EXIST, old_e_key);
248         if (new_e_key != DOES_NOT_EXIST) {
249             TRACE("h0", "hti_copy_entry: lost race to CAS key %p into new entry; found %p",
250                     old_e_key, new_e_key);
251             return hti_copy_entry(old_hti, old_e, key_hash, new_hti); // recursive tail-call
252         }
253     }
254     assert(ht_key_equals(new_e->key, key_hash, key->val, key->len));
255     TRACE("h0", "hti_copy_entry: key %p installed in new old hti %p", key->val, new_hti);
256
257     // Copy the value to the entry in the new table.
258     uint64_t new_e_value = SYNC_CAS(&new_e->value, DOES_NOT_EXIST, old_e_value);
259
260     // If there is a nested copy in progress, we might have installed the key into a dead entry.
261     if (new_e_value == COPIED_VALUE)
262         return hti_copy_entry(old_hti, old_e, key_hash, new_hti->next); // recursive tail-call
263
264     // Mark the old entry as dead.
265     old_e->value = COPIED_VALUE;
266
267     // Update the count if we were the one that completed the copy.
268     if (new_e_value == DOES_NOT_EXIST) {
269         TRACE("h0", "hti_copy_entry: value %p installed in new hti %p", old_e_value, new_hti);
270         SYNC_ADD(&old_hti->count, -1);
271         SYNC_ADD(&new_hti->count, 1);
272         return TRUE;
273     }
274
275     TRACE("h0", "hti_copy_entry: lost race to CAS value %p in new hti; found %p", 
276                 old_e_value, new_e_value);
277     return FALSE; // another thread completed the copy
278 }
279
280 // Compare <expected> with the existing value associated with <key>. If the values match then 
281 // replace the existing value with <new>. If <new> is TOMBSTONE, delete the value associated with 
282 // the key by replacing it with a TOMBSTONE.
283 //
284 // Return the previous value associated with <key>, or DOES_NOT_EXIST if <key> is not in the table
285 // or associated with a TOMBSTONE. If a copy is in progress and <key> has been copied to the next 
286 // table then return COPIED_VALUE. 
287 //
288 // NOTE: the returned value matches <expected> iff the set succeeds
289 //
290 // Certain values of <expected> have special meaning. If <expected> is HT_EXPECT_EXISTS then any 
291 // real value matches (i.e. not a TOMBSTONE or DOES_NOT_EXIST) as long as <key> is in the table. If
292 // <expected> is HT_EXPECT_WHATEVER then skip the test entirely.
293 //
294 static int64_t hti_compare_and_set (hash_table_i_t *hti, uint32_t key_hash, const char *key_val, 
295                                     uint32_t key_len, int64_t expected, int64_t new) {
296     TRACE("h0", "hti_compare_and_set(hti %p key \"%s\")", hti, key_val);
297     TRACE("h0", "hti_compare_and_set(new value %p; caller expects value %p)", new, expected);
298     assert(hti);
299     assert(new != DOES_NOT_EXIST && !IS_TAGGED(new));
300     assert(key_val);
301
302     int is_empty;
303     volatile entry_t *e = hti_lookup(hti, key_hash, key_val, key_len, &is_empty);
304
305     // There is no room for <key>, grow the table and try again.
306     if (e == NULL) {
307         hti_start_copy(hti);
308         return COPIED_VALUE;
309     }
310
311     // Install <key> in the table if it doesn't exist.
312     if (is_empty) {
313         TRACE("h0", "hti_compare_and_set: entry %p is empty", e, 0);
314         if (expected != HT_EXPECT_WHATEVER && expected != HT_EXPECT_NOT_EXISTS)
315             return DOES_NOT_EXIST;
316
317         // No need to do anything, <key> is already deleted.
318         if (new == TOMBSTONE)
319             return DOES_NOT_EXIST;
320
321         // allocate <key>.
322         string_t *key = nbd_malloc(sizeof(uint32_t) + key_len);
323         key->len = key_len;
324         memcpy(key->val, key_val, key_len);
325
326         // CAS <key> into the table. 
327         uint64_t e_key = SYNC_CAS(&e->key, DOES_NOT_EXIST, ((uint64_t)(key_hash >> 16) << 48) | (uint64_t)key);
328
329         // Retry if another thread stole the entry out from under us.
330         if (e_key != DOES_NOT_EXIST) {
331             TRACE("h0", "hti_compare_and_set: key in entry %p is \"%s\"", e, e_key & MASK(48));
332             TRACE("h0", "hti_compare_and_set: lost race to install key \"%s\" in %p", key->val, e);
333             nbd_free(key);
334             return hti_compare_and_set(hti, key_hash, key_val, key_len, expected, new); // tail-call
335         }
336         TRACE("h0", "hti_compare_and_set: installed key \"%s\" in entry %p", key_val, e);
337     }
338
339     // If the entry is in the middle of a copy, the copy must be completed first.
340     int64_t e_value = e->value;
341     TRACE("h0", "hti_compare_and_set: value in entry %p is %p", e, e_value);
342     if (EXPECT_FALSE(IS_TAGGED(e_value))) {
343         int did_copy = hti_copy_entry(hti, e, key_hash, ((volatile hash_table_i_t *)hti)->next);
344         if (did_copy) {
345             SYNC_ADD(&hti->num_entries_copied, 1);
346         }
347         return COPIED_VALUE;
348     }
349
350     // Fail if the old value is not consistent with the caller's expectation.
351     int old_existed = (e_value != TOMBSTONE && e_value != DOES_NOT_EXIST);
352     if (EXPECT_FALSE(expected != HT_EXPECT_WHATEVER && expected != e_value)) {
353         if (EXPECT_FALSE(expected != (old_existed ? HT_EXPECT_EXISTS : HT_EXPECT_NOT_EXISTS))) {
354             TRACE("h0", "hti_compare_and_set: value expected by caller for key \"%s\" not found; "
355                         "found value %p", key_val, e_value);
356             return e_value;
357         }
358     }
359
360     // CAS the value into the entry. Retry if it fails.
361     uint64_t v = SYNC_CAS(&e->value, e_value, new);
362     if (EXPECT_FALSE(v != e_value)) {
363         TRACE("h0", "hti_compare_and_set: value CAS failed; expected %p found %p", e_value, v);
364         return hti_compare_and_set(hti, key_hash, key_val, key_len, expected, new); // recursive tail-call
365     }
366
367     // The set succeeded. Adjust the value count.
368     if (old_existed && new == TOMBSTONE) {
369         SYNC_ADD(&hti->count, -1);
370     } else if (!old_existed && new != TOMBSTONE) {
371         SYNC_ADD(&hti->count, 1);
372     }
373
374     // Return the previous value.
375     TRACE("h0", "hti_compare_and_set: CAS succeeded; old value %p new value %p", e_value, new);
376     return e_value;
377 }
378
379 //
380 static int64_t hti_get (hash_table_i_t *hti, uint32_t key_hash, const char *key_val, uint32_t key_len) {
381     assert(key_val);
382
383     int is_empty;
384     volatile entry_t *e = hti_lookup(hti, key_hash, key_val, key_len, &is_empty);
385
386     // When hti_lookup() returns NULL it means we hit the reprobe limit while
387     // searching the table. In that case, if a copy is in progress the key 
388     // might exist in the copy.
389     if (EXPECT_FALSE(e == NULL)) {
390         if (((volatile hash_table_i_t *)hti)->next != NULL)
391             return hti_get(hti->next, key_hash, key_val, key_len); // recursive tail-call
392         return DOES_NOT_EXIST;
393     }
394
395     if (is_empty)
396         return DOES_NOT_EXIST;
397
398     // If the entry is being copied, finish the copy and retry on the next table.
399     int64_t e_value = e->value;
400     if (EXPECT_FALSE(IS_TAGGED(e_value))) {
401         if (EXPECT_FALSE(e_value != COPIED_VALUE)) {
402             int did_copy = hti_copy_entry(hti, e, key_hash, ((volatile hash_table_i_t *)hti)->next);
403             if (did_copy) {
404                 SYNC_ADD(&hti->num_entries_copied, 1);
405             }
406         }
407         return hti_get(((volatile hash_table_i_t *)hti)->next, key_hash, key_val, key_len); // tail-call
408     }
409
410     return (e_value == TOMBSTONE) ? DOES_NOT_EXIST : e_value;
411 }
412
413 //
414 int64_t ht_get (hash_table_t *ht, const char *key_val, uint32_t key_len) {
415     return hti_get(*ht, murmur32(key_val, key_len), key_val, key_len);
416 }
417
418 //
419 int64_t ht_compare_and_set (hash_table_t *ht, const char *key_val, uint32_t key_len, 
420                             int64_t expected_val, int64_t new_val) {
421
422     assert(key_val);
423     assert(!IS_TAGGED(new_val) && new_val != DOES_NOT_EXIST);
424
425     hash_table_i_t *hti = *ht;
426
427     // Help with an ongoing copy.
428     if (EXPECT_FALSE(hti->next != NULL)) {
429
430         // Reserve some entries for this thread to copy. There is a race condition here because the
431         // fetch and add isn't atomic, but that is ok.
432         int x = hti->scan; 
433         hti->scan = x + ENTRIES_PER_COPY_CHUNK; 
434
435         // <hti->scan> might be larger than the size of the table, if some thread stalls while 
436         // copying. In that case we just wrap around to the begining and make another pass through
437         // the table.
438         volatile entry_t *e = hti->table + (x & MASK(hti->scale));
439
440         // Copy the entries
441         int num_copied = 0, i;
442         for (i = 0; i < ENTRIES_PER_COPY_CHUNK; ++i) {
443             num_copied += hti_copy_entry(hti, e++, 0, hti->next);
444             assert(e <= hti->table + (1 << hti->scale));
445         }
446         if (num_copied != 0) {
447             SYNC_ADD(&hti->num_entries_copied, num_copied);
448         }
449     }
450
451     // Dispose of fully copied tables.
452     while (hti->num_entries_copied == (1 << hti->scale)) {
453         assert(hti->next);
454         if (SYNC_CAS(ht, hti, hti->next) == hti) {
455             nbd_defer_free(hti); 
456         }
457         hti = *ht;
458     }
459
460     int64_t old_val;
461     uint32_t key_hash = murmur32(key_val, key_len);
462     while ((old_val = hti_compare_and_set(hti, key_hash, key_val, key_len, expected_val, new_val)) 
463            == COPIED_VALUE) {
464         assert(hti->next);
465         hti = hti->next;
466     }
467
468     return old_val == TOMBSTONE ? DOES_NOT_EXIST : old_val;
469 }
470
471 // Remove the value in <ht> associated with <key_val>. Returns the value removed, or 
472 // DOES_NOT_EXIST if there was no value for that key.
473 int64_t ht_remove (hash_table_t *ht, const char *key_val, uint32_t key_len) {
474     hash_table_i_t *hti = *ht;
475     int64_t val;
476     uint32_t key_hash = murmur32(key_val, key_len);
477     do {
478         val = hti_compare_and_set(hti, key_hash, key_val, key_len, HT_EXPECT_WHATEVER, TOMBSTONE);
479         if (val != COPIED_VALUE)
480             return val == TOMBSTONE ? DOES_NOT_EXIST : val;
481         assert(hti->next);
482         hti = hti->next;
483         assert(hti);
484     } while (1);
485 }
486
487 // Returns the number of key-values pairs in <ht>
488 uint64_t ht_count (hash_table_t *ht) {
489     hash_table_i_t *hti = *ht;
490     uint64_t count = 0;
491     while (hti) {
492         count += hti->count;
493         hti = hti->next; 
494     }
495     return count;
496 }
497
498 // Allocate and initialize a new hash table.
499 hash_table_t *ht_alloc (void) {
500     hash_table_t *ht = nbd_malloc(sizeof(hash_table_t));
501     *ht = (hash_table_i_t *)hti_alloc(ht, MIN_SCALE);
502     return ht;
503 }
504
505 // Free <ht> and its internal structures.
506 void ht_free (hash_table_t *ht) {
507     hash_table_i_t *hti = *ht;
508     do {
509         hash_table_i_t *next = hti->next;
510         nbd_free(hti);
511         hti = next;
512     } while (hti);
513     nbd_free(ht);
514 }