1/* Hash Tables Implementation.
2 *
3 * This file implements in-memory hash tables with insert/del/replace/find/
4 * get-random-element operations. Hash tables will auto-resize if needed
5 * tables of power of two in size are used, collisions are handled by
6 * chaining. See the source code for more information... :)
7 *
8 * Copyright (c) 2006-2012, Salvatore Sanfilippo <antirez at gmail dot com>
9 * All rights reserved.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions are met:
13 *
14 * * Redistributions of source code must retain the above copyright notice,
15 * this list of conditions and the following disclaimer.
16 * * Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution.
19 * * Neither the name of Redis nor the names of its contributors may be used
20 * to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
24 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 * POSSIBILITY OF SUCH DAMAGE.
34 */
35
36#ifndef __DICT_H
37#define __DICT_H
38
39#include "mt19937-64.h"
40#include <limits.h>
41#include <stdint.h>
42#include <stdlib.h>
43
44#define DICT_OK 0
45#define DICT_ERR 1
46
47typedef struct dictEntry {
48 void *key;
49 union {
50 void *val;
51 uint64_t u64;
52 int64_t s64;
53 double d;
54 } v;
55 struct dictEntry *next; /* Next entry in the same hash bucket. */
56 void *metadata[]; /* An arbitrary number of bytes (starting at a
57 * pointer-aligned address) of size as returned
58 * by dictType's dictEntryMetadataBytes(). */
59} dictEntry;
60
61typedef struct dict dict;
62
63typedef struct dictType {
64 uint64_t (*hashFunction)(const void *key);
65 void *(*keyDup)(dict *d, const void *key);
66 void *(*valDup)(dict *d, const void *obj);
67 int (*keyCompare)(dict *d, const void *key1, const void *key2);
68 void (*keyDestructor)(dict *d, void *key);
69 void (*valDestructor)(dict *d, void *obj);
70 int (*expandAllowed)(size_t moreMem, double usedRatio);
71 /* Allow a dictEntry to carry extra caller-defined metadata. The
72 * extra memory is initialized to 0 when a dictEntry is allocated. */
73 size_t (*dictEntryMetadataBytes)(dict *d);
74} dictType;
75
76#define DICTHT_SIZE(exp) ((exp) == -1 ? 0 : (unsigned long)1<<(exp))
77#define DICTHT_SIZE_MASK(exp) ((exp) == -1 ? 0 : (DICTHT_SIZE(exp))-1)
78
79struct dict {
80 dictType *type;
81
82 dictEntry **ht_table[2];
83 unsigned long ht_used[2];
84
85 long rehashidx; /* rehashing not in progress if rehashidx == -1 */
86
87 /* Keep small vars at end for optimal (minimal) struct padding */
88 int16_t pauserehash; /* If >0 rehashing is paused (<0 indicates coding error) */
89 signed char ht_size_exp[2]; /* exponent of size. (size = 1<<exp) */
90};
91
92/* If safe is set to 1 this is a safe iterator, that means, you can call
93 * dictAdd, dictFind, and other functions against the dictionary even while
94 * iterating. Otherwise it is a non safe iterator, and only dictNext()
95 * should be called while iterating. */
96typedef struct dictIterator {
97 dict *d;
98 long index;
99 int table, safe;
100 dictEntry *entry, *nextEntry;
101 /* unsafe iterator fingerprint for misuse detection. */
102 unsigned long long fingerprint;
103} dictIterator;
104
105typedef void (dictScanFunction)(void *privdata, const dictEntry *de);
106typedef void (dictScanBucketFunction)(dict *d, dictEntry **bucketref);
107
108/* This is the initial size of every hash table */
109#define DICT_HT_INITIAL_EXP 2
110#define DICT_HT_INITIAL_SIZE (1<<(DICT_HT_INITIAL_EXP))
111
112/* ------------------------------- Macros ------------------------------------*/
113#define dictFreeVal(d, entry) \
114 if ((d)->type->valDestructor) \
115 (d)->type->valDestructor((d), (entry)->v.val)
116
117#define dictSetVal(d, entry, _val_) do { \
118 if ((d)->type->valDup) \
119 (entry)->v.val = (d)->type->valDup((d), _val_); \
120 else \
121 (entry)->v.val = (_val_); \
122} while(0)
123
124#define dictSetSignedIntegerVal(entry, _val_) \
125 do { (entry)->v.s64 = _val_; } while(0)
126
127#define dictSetUnsignedIntegerVal(entry, _val_) \
128 do { (entry)->v.u64 = _val_; } while(0)
129
130#define dictSetDoubleVal(entry, _val_) \
131 do { (entry)->v.d = _val_; } while(0)
132
133#define dictFreeKey(d, entry) \
134 if ((d)->type->keyDestructor) \
135 (d)->type->keyDestructor((d), (entry)->key)
136
137#define dictSetKey(d, entry, _key_) do { \
138 if ((d)->type->keyDup) \
139 (entry)->key = (d)->type->keyDup((d), _key_); \
140 else \
141 (entry)->key = (_key_); \
142} while(0)
143
144#define dictCompareKeys(d, key1, key2) \
145 (((d)->type->keyCompare) ? \
146 (d)->type->keyCompare((d), key1, key2) : \
147 (key1) == (key2))
148
149#define dictMetadata(entry) (&(entry)->metadata)
150#define dictMetadataSize(d) ((d)->type->dictEntryMetadataBytes \
151 ? (d)->type->dictEntryMetadataBytes(d) : 0)
152
153#define dictHashKey(d, key) (d)->type->hashFunction(key)
154#define dictGetKey(he) ((he)->key)
155#define dictGetVal(he) ((he)->v.val)
156#define dictGetSignedIntegerVal(he) ((he)->v.s64)
157#define dictGetUnsignedIntegerVal(he) ((he)->v.u64)
158#define dictGetDoubleVal(he) ((he)->v.d)
159#define dictSlots(d) (DICTHT_SIZE((d)->ht_size_exp[0])+DICTHT_SIZE((d)->ht_size_exp[1]))
160#define dictSize(d) ((d)->ht_used[0]+(d)->ht_used[1])
161#define dictIsRehashing(d) ((d)->rehashidx != -1)
162#define dictPauseRehashing(d) (d)->pauserehash++
163#define dictResumeRehashing(d) (d)->pauserehash--
164
165/* If our unsigned long type can store a 64 bit number, use a 64 bit PRNG. */
166#if ULONG_MAX >= 0xffffffffffffffff
167#define randomULong() ((unsigned long) genrand64_int64())
168#else
169#define randomULong() random()
170#endif
171
172/* API */
173dict *dictCreate(dictType *type);
174int dictExpand(dict *d, unsigned long size);
175int dictTryExpand(dict *d, unsigned long size);
176int dictAdd(dict *d, void *key, void *val);
177dictEntry *dictAddRaw(dict *d, void *key, dictEntry **existing);
178dictEntry *dictAddOrFind(dict *d, void *key);
179int dictReplace(dict *d, void *key, void *val);
180int dictDelete(dict *d, const void *key);
181dictEntry *dictUnlink(dict *d, const void *key);
182void dictFreeUnlinkedEntry(dict *d, dictEntry *he);
183void dictRelease(dict *d);
184dictEntry * dictFind(dict *d, const void *key);
185void *dictFetchValue(dict *d, const void *key);
186int dictResize(dict *d);
187dictIterator *dictGetIterator(dict *d);
188dictIterator *dictGetSafeIterator(dict *d);
189dictEntry *dictNext(dictIterator *iter);
190void dictReleaseIterator(dictIterator *iter);
191dictEntry *dictGetRandomKey(dict *d);
192dictEntry *dictGetFairRandomKey(dict *d);
193unsigned int dictGetSomeKeys(dict *d, dictEntry **des, unsigned int count);
194void dictGetStats(char *buf, size_t bufsize, dict *d);
195uint64_t dictGenHashFunction(const void *key, size_t len);
196uint64_t dictGenCaseHashFunction(const unsigned char *buf, size_t len);
197void dictEmpty(dict *d, void(callback)(dict*));
198void dictEnableResize(void);
199void dictDisableResize(void);
200int dictRehash(dict *d, int n);
201int dictRehashMilliseconds(dict *d, int ms);
202void dictSetHashFunctionSeed(uint8_t *seed);
203uint8_t *dictGetHashFunctionSeed(void);
204unsigned long dictScan(dict *d, unsigned long v, dictScanFunction *fn, dictScanBucketFunction *bucketfn, void *privdata);
205uint64_t dictGetHash(dict *d, const void *key);
206dictEntry **dictFindEntryRefByPtrAndHash(dict *d, const void *oldptr, uint64_t hash);
207
208#ifdef REDIS_TEST
209int dictTest(int argc, char *argv[], int flags);
210#endif
211
212#endif /* __DICT_H */
213