src/dict.h

   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-2010, 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 #define DICT_OK 0
  40 #define DICT_ERR 1
  41
  42 /* Unused arguments generate annoying warnings... */
  43 #define DICT_NOTUSED(V) ((void) V)
  44
  45 typedef struct dictEntry {
  46     void *key;
  47     void *val;
  48     struct dictEntry *next;
  49 } dictEntry;
  50
  51 typedef struct dictType {
  52     unsigned int (*hashFunction)(const void *key);
  53     void *(*keyDup)(void *privdata, const void *key);
  54     void *(*valDup)(void *privdata, const void *obj);
  55     int (*keyCompare)(void *privdata, const void *key1, const void *key2);
  56     void (*keyDestructor)(void *privdata, void *key);
  57     void (*valDestructor)(void *privdata, void *obj);
  58 } dictType;
  59
  60 /* This is our hash table structure. Every dictionary has two of this as we
  61  * implement incremental rehashing, for the old to the new table. */
  62 typedef struct dictht {
  63     dictEntry **table;
  64     unsigned long size;
  65     unsigned long sizemask;
  66     unsigned long used;
  67 } dictht;
  68
  69 typedef struct dict {
  70     dictType *type;
  71     void *privdata;
  72     dictht ht[2];
  73     int rehashidx; /* rehashing not in progress if rehashidx == -1 */
  74     int iterators; /* number of iterators currently running */
  75 } dict;
  76
  77 /* If safe is set to 1 this is a safe iteartor, that means, you can call
  78  * dictAdd, dictFind, and other functions against the dictionary even while
  79  * iterating. Otherwise it is a non safe iterator, and only dictNext()
  80  * should be called while iterating. */
  81 typedef struct dictIterator {
  82     dict *d;
  83     int table, index, safe;
  84     dictEntry *entry, *nextEntry;
  85 } dictIterator;
  86
  87 /* This is the initial size of every hash table */
  88 #define DICT_HT_INITIAL_SIZE     4
  89
  90 /* ------------------------------- Macros ------------------------------------*/
  91 #define dictFreeEntryVal(d, entry) \
  92     if ((d)->type->valDestructor) \
  93         (d)->type->valDestructor((d)->privdata, (entry)->val)
  94
  95 #define dictSetHashVal(d, entry, _val_) do { \
  96     if ((d)->type->valDup) \
  97         entry->val = (d)->type->valDup((d)->privdata, _val_); \
  98     else \
  99         entry->val = (_val_); \
 100 } while(0)
 101
 102 #define dictFreeEntryKey(d, entry) \
 103     if ((d)->type->keyDestructor) \
 104         (d)->type->keyDestructor((d)->privdata, (entry)->key)
 105
 106 #define dictSetHashKey(d, entry, _key_) do { \
 107     if ((d)->type->keyDup) \
 108         entry->key = (d)->type->keyDup((d)->privdata, _key_); \
 109     else \
 110         entry->key = (_key_); \
 111 } while(0)
 112
 113 #define dictCompareHashKeys(d, key1, key2) \
 114     (((d)->type->keyCompare) ? \
 115         (d)->type->keyCompare((d)->privdata, key1, key2) : \
 116         (key1) == (key2))
 117
 118 #define dictHashKey(d, key) (d)->type->hashFunction(key)
 119
 120 #define dictGetEntryKey(he) ((he)->key)
 121 #define dictGetEntryVal(he) ((he)->val)
 122 #define dictSlots(d) ((d)->ht[0].size+(d)->ht[1].size)
 123 #define dictSize(d) ((d)->ht[0].used+(d)->ht[1].used)
 124 #define dictIsRehashing(ht) ((ht)->rehashidx != -1)
 125
 126 /* API */
 127 dict *dictCreate(dictType *type, void *privDataPtr);
 128 int dictExpand(dict *d, unsigned long size);
 129 int dictAdd(dict *d, void *key, void *val);
 130 int dictReplace(dict *d, void *key, void *val);
 131 int dictDelete(dict *d, const void *key);
 132 int dictDeleteNoFree(dict *d, const void *key);
 133 void dictRelease(dict *d);
 134 dictEntry * dictFind(dict *d, const void *key);
 135 void *dictFetchValue(dict *d, const void *key);
 136 int dictResize(dict *d);
 137 dictIterator *dictGetIterator(dict *d);
 138 dictIterator *dictGetSafeIterator(dict *d);
 139 dictEntry *dictNext(dictIterator *iter);
 140 void dictReleaseIterator(dictIterator *iter);
 141 dictEntry *dictGetRandomKey(dict *d);
 142 void dictPrintStats(dict *d);
 143 unsigned int dictGenHashFunction(const unsigned char *buf, int len);
 144 unsigned int dictGenCaseHashFunction(const unsigned char *buf, int len);
 145 void dictEmpty(dict *d);
 146 void dictEnableResize(void);
 147 void dictDisableResize(void);
 148 int dictRehash(dict *d, int n);
 149 int dictRehashMilliseconds(dict *d, int ms);
 150
 151 /* Hash table types */
 152 extern dictType dictTypeHeapStringCopyKey;
 153 extern dictType dictTypeHeapStrings;
 154 extern dictType dictTypeHeapStringCopyKeyValue;
 155
 156 #endif /* __DICT_H */