1/* 2 +----------------------------------------------------------------------+ 3 | Zend Engine | 4 +----------------------------------------------------------------------+ 5 | Copyright (c) 1998-2013 Zend Technologies Ltd. (http://www.zend.com) | 6 +----------------------------------------------------------------------+ 7 | This source file is subject to version 2.00 of the Zend license, | 8 | that is bundled with this package in the file LICENSE, and is | 9 | available through the world-wide-web at the following url: | 10 | http://www.zend.com/license/2_00.txt. | 11 | If you did not receive a copy of the Zend license and are unable to | 12 | obtain it through the world-wide-web, please send a note to | 13 | license@zend.com so we can mail you a copy immediately. | 14 +----------------------------------------------------------------------+ 15 | Authors: Andi Gutmans <andi@zend.com> | 16 | Zeev Suraski <zeev@zend.com> | 17 +----------------------------------------------------------------------+ 18*/ 19 20/* $Id$ */ 21 22#ifndef ZEND_HASH_H 23#define ZEND_HASH_H 24 25#include <sys/types.h> 26#include "zend.h" 27 28#define HASH_KEY_IS_STRING 1 29#define HASH_KEY_IS_LONG 2 30#define HASH_KEY_NON_EXISTANT 3 31 32#define HASH_UPDATE (1<<0) 33#define HASH_ADD (1<<1) 34#define HASH_NEXT_INSERT (1<<2) 35 36#define HASH_DEL_KEY 0 37#define HASH_DEL_INDEX 1 38#define HASH_DEL_KEY_QUICK 2 39 40#define HASH_UPDATE_KEY_IF_NONE 0 41#define HASH_UPDATE_KEY_IF_BEFORE 1 42#define HASH_UPDATE_KEY_IF_AFTER 2 43#define HASH_UPDATE_KEY_ANYWAY 3 44 45typedef ulong (*hash_func_t)(const char *arKey, uint nKeyLength); 46typedef int (*compare_func_t)(const void *, const void * TSRMLS_DC); 47typedef void (*sort_func_t)(void *, size_t, register size_t, compare_func_t TSRMLS_DC); 48typedef void (*dtor_func_t)(void *pDest); 49typedef void (*copy_ctor_func_t)(void *pElement); 50typedef void (*copy_ctor_param_func_t)(void *pElement, void *pParam); 51 52struct _hashtable; 53 54typedef struct bucket { 55 ulong h; /* Used for numeric indexing */ 56 uint nKeyLength; 57 void *pData; 58 void *pDataPtr; 59 struct bucket *pListNext; 60 struct bucket *pListLast; 61 struct bucket *pNext; 62 struct bucket *pLast; 63 const char *arKey; 64} Bucket; 65 66typedef struct _hashtable { 67 uint nTableSize; 68 uint nTableMask; 69 uint nNumOfElements; 70 ulong nNextFreeElement; 71 Bucket *pInternalPointer; /* Used for element traversal */ 72 Bucket *pListHead; 73 Bucket *pListTail; 74 Bucket **arBuckets; 75 dtor_func_t pDestructor; 76 zend_bool persistent; 77 unsigned char nApplyCount; 78 zend_bool bApplyProtection; 79#if ZEND_DEBUG 80 int inconsistent; 81#endif 82} HashTable; 83 84 85typedef struct _zend_hash_key { 86 const char *arKey; 87 uint nKeyLength; 88 ulong h; 89} zend_hash_key; 90 91 92typedef zend_bool (*merge_checker_func_t)(HashTable *target_ht, void *source_data, zend_hash_key *hash_key, void *pParam); 93 94typedef Bucket* HashPosition; 95 96BEGIN_EXTERN_C() 97 98/* startup/shutdown */ 99ZEND_API int _zend_hash_init(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent ZEND_FILE_LINE_DC); 100ZEND_API int _zend_hash_init_ex(HashTable *ht, uint nSize, hash_func_t pHashFunction, dtor_func_t pDestructor, zend_bool persistent, zend_bool bApplyProtection ZEND_FILE_LINE_DC); 101ZEND_API void zend_hash_destroy(HashTable *ht); 102ZEND_API void zend_hash_clean(HashTable *ht); 103#define zend_hash_init(ht, nSize, pHashFunction, pDestructor, persistent) _zend_hash_init((ht), (nSize), (pHashFunction), (pDestructor), (persistent) ZEND_FILE_LINE_CC) 104#define zend_hash_init_ex(ht, nSize, pHashFunction, pDestructor, persistent, bApplyProtection) _zend_hash_init_ex((ht), (nSize), (pHashFunction), (pDestructor), (persistent), (bApplyProtection) ZEND_FILE_LINE_CC) 105 106/* additions/updates/changes */ 107ZEND_API int _zend_hash_add_or_update(HashTable *ht, const char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC); 108#define zend_hash_update(ht, arKey, nKeyLength, pData, nDataSize, pDest) \ 109 _zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC) 110#define zend_hash_add(ht, arKey, nKeyLength, pData, nDataSize, pDest) \ 111 _zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, HASH_ADD ZEND_FILE_LINE_CC) 112 113ZEND_API int _zend_hash_quick_add_or_update(HashTable *ht, const char *arKey, uint nKeyLength, ulong h, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC); 114#define zend_hash_quick_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest) \ 115 _zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC) 116#define zend_hash_quick_add(ht, arKey, nKeyLength, h, pData, nDataSize, pDest) \ 117 _zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, HASH_ADD ZEND_FILE_LINE_CC) 118 119ZEND_API int _zend_hash_index_update_or_next_insert(HashTable *ht, ulong h, void *pData, uint nDataSize, void **pDest, int flag ZEND_FILE_LINE_DC); 120#define zend_hash_index_update(ht, h, pData, nDataSize, pDest) \ 121 _zend_hash_index_update_or_next_insert(ht, h, pData, nDataSize, pDest, HASH_UPDATE ZEND_FILE_LINE_CC) 122#define zend_hash_next_index_insert(ht, pData, nDataSize, pDest) \ 123 _zend_hash_index_update_or_next_insert(ht, 0, pData, nDataSize, pDest, HASH_NEXT_INSERT ZEND_FILE_LINE_CC) 124 125ZEND_API int zend_hash_add_empty_element(HashTable *ht, const char *arKey, uint nKeyLength); 126 127 128#define ZEND_HASH_APPLY_KEEP 0 129#define ZEND_HASH_APPLY_REMOVE 1<<0 130#define ZEND_HASH_APPLY_STOP 1<<1 131 132typedef int (*apply_func_t)(void *pDest TSRMLS_DC); 133typedef int (*apply_func_arg_t)(void *pDest, void *argument TSRMLS_DC); 134typedef int (*apply_func_args_t)(void *pDest TSRMLS_DC, int num_args, va_list args, zend_hash_key *hash_key); 135 136ZEND_API void zend_hash_graceful_destroy(HashTable *ht); 137ZEND_API void zend_hash_graceful_reverse_destroy(HashTable *ht); 138ZEND_API void zend_hash_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC); 139ZEND_API void zend_hash_apply_with_argument(HashTable *ht, apply_func_arg_t apply_func, void * TSRMLS_DC); 140ZEND_API void zend_hash_apply_with_arguments(HashTable *ht TSRMLS_DC, apply_func_args_t apply_func, int, ...); 141 142/* This function should be used with special care (in other words, 143 * it should usually not be used). When used with the ZEND_HASH_APPLY_STOP 144 * return value, it assumes things about the order of the elements in the hash. 145 * Also, it does not provide the same kind of reentrancy protection that 146 * the standard apply functions do. 147 */ 148ZEND_API void zend_hash_reverse_apply(HashTable *ht, apply_func_t apply_func TSRMLS_DC); 149 150 151/* Deletes */ 152ZEND_API int zend_hash_del_key_or_index(HashTable *ht, const char *arKey, uint nKeyLength, ulong h, int flag); 153#define zend_hash_del(ht, arKey, nKeyLength) \ 154 zend_hash_del_key_or_index(ht, arKey, nKeyLength, 0, HASH_DEL_KEY) 155#define zend_hash_quick_del(ht, arKey, nKeyLength, h) \ 156 zend_hash_del_key_or_index(ht, arKey, nKeyLength, h, HASH_DEL_KEY_QUICK) 157#define zend_hash_index_del(ht, h) \ 158 zend_hash_del_key_or_index(ht, NULL, 0, h, HASH_DEL_INDEX) 159 160ZEND_API ulong zend_get_hash_value(const char *arKey, uint nKeyLength); 161 162/* Data retreival */ 163ZEND_API int zend_hash_find(const HashTable *ht, const char *arKey, uint nKeyLength, void **pData); 164ZEND_API int zend_hash_quick_find(const HashTable *ht, const char *arKey, uint nKeyLength, ulong h, void **pData); 165ZEND_API int zend_hash_index_find(const HashTable *ht, ulong h, void **pData); 166 167/* Misc */ 168ZEND_API int zend_hash_exists(const HashTable *ht, const char *arKey, uint nKeyLength); 169ZEND_API int zend_hash_quick_exists(const HashTable *ht, const char *arKey, uint nKeyLength, ulong h); 170ZEND_API int zend_hash_index_exists(const HashTable *ht, ulong h); 171ZEND_API ulong zend_hash_next_free_element(const HashTable *ht); 172 173/* traversing */ 174#define zend_hash_has_more_elements_ex(ht, pos) \ 175 (zend_hash_get_current_key_type_ex(ht, pos) == HASH_KEY_NON_EXISTANT ? FAILURE : SUCCESS) 176ZEND_API int zend_hash_move_forward_ex(HashTable *ht, HashPosition *pos); 177ZEND_API int zend_hash_move_backwards_ex(HashTable *ht, HashPosition *pos); 178ZEND_API int zend_hash_get_current_key_ex(const HashTable *ht, char **str_index, uint *str_length, ulong *num_index, zend_bool duplicate, HashPosition *pos); 179ZEND_API void zend_hash_get_current_key_zval_ex(const HashTable *ht, zval *key, HashPosition *pos); 180ZEND_API int zend_hash_get_current_key_type_ex(HashTable *ht, HashPosition *pos); 181ZEND_API int zend_hash_get_current_data_ex(HashTable *ht, void **pData, HashPosition *pos); 182ZEND_API void zend_hash_internal_pointer_reset_ex(HashTable *ht, HashPosition *pos); 183ZEND_API void zend_hash_internal_pointer_end_ex(HashTable *ht, HashPosition *pos); 184ZEND_API int zend_hash_update_current_key_ex(HashTable *ht, int key_type, const char *str_index, uint str_length, ulong num_index, int mode, HashPosition *pos); 185 186typedef struct _HashPointer { 187 HashPosition pos; 188 ulong h; 189} HashPointer; 190 191ZEND_API int zend_hash_get_pointer(const HashTable *ht, HashPointer *ptr); 192ZEND_API int zend_hash_set_pointer(HashTable *ht, const HashPointer *ptr); 193 194#define zend_hash_has_more_elements(ht) \ 195 zend_hash_has_more_elements_ex(ht, NULL) 196#define zend_hash_move_forward(ht) \ 197 zend_hash_move_forward_ex(ht, NULL) 198#define zend_hash_move_backwards(ht) \ 199 zend_hash_move_backwards_ex(ht, NULL) 200#define zend_hash_get_current_key(ht, str_index, num_index, duplicate) \ 201 zend_hash_get_current_key_ex(ht, str_index, NULL, num_index, duplicate, NULL) 202#define zend_hash_get_current_key_zval(ht, key) \ 203 zend_hash_get_current_key_zval_ex(ht, key, NULL) 204#define zend_hash_get_current_key_type(ht) \ 205 zend_hash_get_current_key_type_ex(ht, NULL) 206#define zend_hash_get_current_data(ht, pData) \ 207 zend_hash_get_current_data_ex(ht, pData, NULL) 208#define zend_hash_internal_pointer_reset(ht) \ 209 zend_hash_internal_pointer_reset_ex(ht, NULL) 210#define zend_hash_internal_pointer_end(ht) \ 211 zend_hash_internal_pointer_end_ex(ht, NULL) 212#define zend_hash_update_current_key(ht, key_type, str_index, str_length, num_index) \ 213 zend_hash_update_current_key_ex(ht, key_type, str_index, str_length, num_index, HASH_UPDATE_KEY_ANYWAY, NULL) 214 215/* Copying, merging and sorting */ 216ZEND_API void zend_hash_copy(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size); 217ZEND_API void _zend_hash_merge(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, void *tmp, uint size, int overwrite ZEND_FILE_LINE_DC); 218ZEND_API void zend_hash_merge_ex(HashTable *target, HashTable *source, copy_ctor_func_t pCopyConstructor, uint size, merge_checker_func_t pMergeSource, void *pParam); 219ZEND_API int zend_hash_sort(HashTable *ht, sort_func_t sort_func, compare_func_t compare_func, int renumber TSRMLS_DC); 220ZEND_API int zend_hash_compare(HashTable *ht1, HashTable *ht2, compare_func_t compar, zend_bool ordered TSRMLS_DC); 221ZEND_API int zend_hash_minmax(const HashTable *ht, compare_func_t compar, int flag, void **pData TSRMLS_DC); 222 223#define zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite) \ 224 _zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite ZEND_FILE_LINE_CC) 225 226ZEND_API int zend_hash_num_elements(const HashTable *ht); 227 228ZEND_API int zend_hash_rehash(HashTable *ht); 229 230/* 231 * DJBX33A (Daniel J. Bernstein, Times 33 with Addition) 232 * 233 * This is Daniel J. Bernstein's popular `times 33' hash function as 234 * posted by him years ago on comp.lang.c. It basically uses a function 235 * like ``hash(i) = hash(i-1) * 33 + str[i]''. This is one of the best 236 * known hash functions for strings. Because it is both computed very 237 * fast and distributes very well. 238 * 239 * The magic of number 33, i.e. why it works better than many other 240 * constants, prime or not, has never been adequately explained by 241 * anyone. So I try an explanation: if one experimentally tests all 242 * multipliers between 1 and 256 (as RSE did now) one detects that even 243 * numbers are not useable at all. The remaining 128 odd numbers 244 * (except for the number 1) work more or less all equally well. They 245 * all distribute in an acceptable way and this way fill a hash table 246 * with an average percent of approx. 86%. 247 * 248 * If one compares the Chi^2 values of the variants, the number 33 not 249 * even has the best value. But the number 33 and a few other equally 250 * good numbers like 17, 31, 63, 127 and 129 have nevertheless a great 251 * advantage to the remaining numbers in the large set of possible 252 * multipliers: their multiply operation can be replaced by a faster 253 * operation based on just one shift plus either a single addition 254 * or subtraction operation. And because a hash function has to both 255 * distribute good _and_ has to be very fast to compute, those few 256 * numbers should be preferred and seems to be the reason why Daniel J. 257 * Bernstein also preferred it. 258 * 259 * 260 * -- Ralf S. Engelschall <rse@engelschall.com> 261 */ 262 263static inline ulong zend_inline_hash_func(const char *arKey, uint nKeyLength) 264{ 265 register ulong hash = 5381; 266 267 /* variant with the hash unrolled eight times */ 268 for (; nKeyLength >= 8; nKeyLength -= 8) { 269 hash = ((hash << 5) + hash) + *arKey++; 270 hash = ((hash << 5) + hash) + *arKey++; 271 hash = ((hash << 5) + hash) + *arKey++; 272 hash = ((hash << 5) + hash) + *arKey++; 273 hash = ((hash << 5) + hash) + *arKey++; 274 hash = ((hash << 5) + hash) + *arKey++; 275 hash = ((hash << 5) + hash) + *arKey++; 276 hash = ((hash << 5) + hash) + *arKey++; 277 } 278 switch (nKeyLength) { 279 case 7: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 280 case 6: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 281 case 5: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 282 case 4: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 283 case 3: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 284 case 2: hash = ((hash << 5) + hash) + *arKey++; /* fallthrough... */ 285 case 1: hash = ((hash << 5) + hash) + *arKey++; break; 286 case 0: break; 287EMPTY_SWITCH_DEFAULT_CASE() 288 } 289 return hash; 290} 291 292 293ZEND_API ulong zend_hash_func(const char *arKey, uint nKeyLength); 294 295#if ZEND_DEBUG 296/* debug */ 297void zend_hash_display_pListTail(const HashTable *ht); 298void zend_hash_display(const HashTable *ht); 299#endif 300 301END_EXTERN_C() 302 303#define ZEND_INIT_SYMTABLE(ht) \ 304 ZEND_INIT_SYMTABLE_EX(ht, 2, 0) 305 306#define ZEND_INIT_SYMTABLE_EX(ht, n, persistent) \ 307 zend_hash_init(ht, n, NULL, ZVAL_PTR_DTOR, persistent) 308 309#define ZEND_HANDLE_NUMERIC_EX(key, length, idx, func) do { \ 310 register const char *tmp = key; \ 311 \ 312 if (*tmp == '-') { \ 313 tmp++; \ 314 } \ 315 if (*tmp >= '0' && *tmp <= '9') { /* possibly a numeric index */ \ 316 const char *end = key + length - 1; \ 317 \ 318 if ((*end != '\0') /* not a null terminated string */ \ 319 || (*tmp == '0' && length > 2) /* numbers with leading zeros */ \ 320 || (end - tmp > MAX_LENGTH_OF_LONG - 1) /* number too long */ \ 321 || (SIZEOF_LONG == 4 && \ 322 end - tmp == MAX_LENGTH_OF_LONG - 1 && \ 323 *tmp > '2')) { /* overflow */ \ 324 break; \ 325 } \ 326 idx = (*tmp - '0'); \ 327 while (++tmp != end && *tmp >= '0' && *tmp <= '9') { \ 328 idx = (idx * 10) + (*tmp - '0'); \ 329 } \ 330 if (tmp == end) { \ 331 if (*key == '-') { \ 332 if (idx-1 > LONG_MAX) { /* overflow */ \ 333 break; \ 334 } \ 335 idx = 0 - idx; \ 336 } else if (idx > LONG_MAX) { /* overflow */ \ 337 break; \ 338 } \ 339 func; \ 340 } \ 341 } \ 342} while (0) 343 344#define ZEND_HANDLE_NUMERIC(key, length, func) do { \ 345 ulong idx; \ 346 \ 347 ZEND_HANDLE_NUMERIC_EX(key, length, idx, return func); \ 348} while (0) 349 350static inline int zend_symtable_update(HashTable *ht, const char *arKey, uint nKeyLength, void *pData, uint nDataSize, void **pDest) \ 351{ 352 ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_update(ht, idx, pData, nDataSize, pDest)); 353 return zend_hash_update(ht, arKey, nKeyLength, pData, nDataSize, pDest); 354} 355 356 357static inline int zend_symtable_del(HashTable *ht, const char *arKey, uint nKeyLength) 358{ 359 ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_del(ht, idx)); 360 return zend_hash_del(ht, arKey, nKeyLength); 361} 362 363 364static inline int zend_symtable_find(HashTable *ht, const char *arKey, uint nKeyLength, void **pData) 365{ 366 ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_find(ht, idx, pData)); 367 return zend_hash_find(ht, arKey, nKeyLength, pData); 368} 369 370 371static inline int zend_symtable_exists(HashTable *ht, const char *arKey, uint nKeyLength) 372{ 373 ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_index_exists(ht, idx)); 374 return zend_hash_exists(ht, arKey, nKeyLength); 375} 376 377static inline int zend_symtable_update_current_key_ex(HashTable *ht, const char *arKey, uint nKeyLength, int mode, HashPosition *pos) 378{ 379 ZEND_HANDLE_NUMERIC(arKey, nKeyLength, zend_hash_update_current_key_ex(ht, HASH_KEY_IS_LONG, NULL, 0, idx, mode, pos)); 380 return zend_hash_update_current_key_ex(ht, HASH_KEY_IS_STRING, arKey, nKeyLength, 0, mode, pos); 381} 382#define zend_symtable_update_current_key(ht,arKey,nKeyLength,mode) \ 383 zend_symtable_update_current_key_ex(ht, arKey, nKeyLength, mode, NULL) 384 385 386#endif /* ZEND_HASH_H */ 387 388/* 389 * Local variables: 390 * tab-width: 4 391 * c-basic-offset: 4 392 * indent-tabs-mode: t 393 * End: 394 */ 395