/gecko_api/include/pldhash.h
C++ Header | 593 lines | 183 code | 53 blank | 357 comment | 5 complexity | 50218bc8f7e62095be27ad6da6f87f3f MD5 | raw file
1/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2/* ***** BEGIN LICENSE BLOCK ***** 3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 4 * 5 * The contents of this file are subject to the Mozilla Public License Version 6 * 1.1 (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * http://www.mozilla.org/MPL/ 9 * 10 * Software distributed under the License is distributed on an "AS IS" basis, 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 12 * for the specific language governing rights and limitations under the 13 * License. 14 * 15 * The Original Code is Mozilla JavaScript code. 16 * 17 * The Initial Developer of the Original Code is 18 * Netscape Communications Corporation. 19 * Portions created by the Initial Developer are Copyright (C) 1999-2001 20 * the Initial Developer. All Rights Reserved. 21 * 22 * Contributor(s): 23 * Brendan Eich <brendan@mozilla.org> (Original Author) 24 * 25 * Alternatively, the contents of this file may be used under the terms of 26 * either of the GNU General Public License Version 2 or later (the "GPL"), 27 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 28 * in which case the provisions of the GPL or the LGPL are applicable instead 29 * of those above. If you wish to allow use of your version of this file only 30 * under the terms of either the GPL or the LGPL, and not to allow others to 31 * use your version of this file under the terms of the MPL, indicate your 32 * decision by deleting the provisions above and replace them with the notice 33 * and other provisions required by the GPL or the LGPL. If you do not delete 34 * the provisions above, a recipient may use your version of this file under 35 * the terms of any one of the MPL, the GPL or the LGPL. 36 * 37 * ***** END LICENSE BLOCK ***** */ 38 39#ifndef pldhash_h___ 40#define pldhash_h___ 41/* 42 * Double hashing, a la Knuth 6. 43 * GENERATED BY js/src/plify_jsdhash.sed -- DO NOT EDIT!!! 44 */ 45#include "nscore.h" 46 47PR_BEGIN_EXTERN_C 48 49#if defined(__GNUC__) && defined(__i386__) && (__GNUC__ >= 3) && !defined(XP_OS2) 50#define PL_DHASH_FASTCALL __attribute__ ((regparm (3),stdcall)) 51#elif defined(XP_WIN) 52#define PL_DHASH_FASTCALL __fastcall 53#else 54#define PL_DHASH_FASTCALL 55#endif 56 57#ifdef DEBUG_XXXbrendan 58#define PL_DHASHMETER 1 59#endif 60 61/* Table size limit, do not equal or exceed (see min&maxAlphaFrac, below). */ 62#undef PL_DHASH_SIZE_LIMIT 63#define PL_DHASH_SIZE_LIMIT PR_BIT(24) 64 65/* Minimum table size, or gross entry count (net is at most .75 loaded). */ 66#ifndef PL_DHASH_MIN_SIZE 67#define PL_DHASH_MIN_SIZE 16 68#elif (PL_DHASH_MIN_SIZE & (PL_DHASH_MIN_SIZE - 1)) != 0 69#error "PL_DHASH_MIN_SIZE must be a power of two!" 70#endif 71 72/* 73 * Multiplicative hash uses an unsigned 32 bit integer and the golden ratio, 74 * expressed as a fixed-point 32-bit fraction. 75 */ 76#define PL_DHASH_BITS 32 77#define PL_DHASH_GOLDEN_RATIO 0x9E3779B9U 78 79/* Primitive and forward-struct typedefs. */ 80typedef PRUint32 PLDHashNumber; 81typedef struct PLDHashEntryHdr PLDHashEntryHdr; 82typedef struct PLDHashEntryStub PLDHashEntryStub; 83typedef struct PLDHashTable PLDHashTable; 84typedef struct PLDHashTableOps PLDHashTableOps; 85 86/* 87 * Table entry header structure. 88 * 89 * In order to allow in-line allocation of key and value, we do not declare 90 * either here. Instead, the API uses const void *key as a formal parameter. 91 * The key need not be stored in the entry; it may be part of the value, but 92 * need not be stored at all. 93 * 94 * Callback types are defined below and grouped into the PLDHashTableOps 95 * structure, for single static initialization per hash table sub-type. 96 * 97 * Each hash table sub-type should nest the PLDHashEntryHdr structure at the 98 * front of its particular entry type. The keyHash member contains the result 99 * of multiplying the hash code returned from the hashKey callback (see below) 100 * by PL_DHASH_GOLDEN_RATIO, then constraining the result to avoid the magic 0 101 * and 1 values. The stored keyHash value is table size invariant, and it is 102 * maintained automatically by PL_DHashTableOperate -- users should never set 103 * it, and its only uses should be via the entry macros below. 104 * 105 * The PL_DHASH_ENTRY_IS_LIVE macro tests whether entry is neither free nor 106 * removed. An entry may be either busy or free; if busy, it may be live or 107 * removed. Consumers of this API should not access members of entries that 108 * are not live. 109 * 110 * However, use PL_DHASH_ENTRY_IS_BUSY for faster liveness testing of entries 111 * returned by PL_DHashTableOperate, as PL_DHashTableOperate never returns a 112 * non-live, busy (i.e., removed) entry pointer to its caller. See below for 113 * more details on PL_DHashTableOperate's calling rules. 114 */ 115struct PLDHashEntryHdr { 116 PLDHashNumber keyHash; /* every entry must begin like this */ 117}; 118 119#define PL_DHASH_ENTRY_IS_FREE(entry) ((entry)->keyHash == 0) 120#define PL_DHASH_ENTRY_IS_BUSY(entry) (!PL_DHASH_ENTRY_IS_FREE(entry)) 121#define PL_DHASH_ENTRY_IS_LIVE(entry) ((entry)->keyHash >= 2) 122 123/* 124 * A PLDHashTable is currently 8 words (without the PL_DHASHMETER overhead) 125 * on most architectures, and may be allocated on the stack or within another 126 * structure or class (see below for the Init and Finish functions to use). 127 * 128 * To decide whether to use double hashing vs. chaining, we need to develop a 129 * trade-off relation, as follows: 130 * 131 * Let alpha be the load factor, esize the entry size in words, count the 132 * entry count, and pow2 the power-of-two table size in entries. 133 * 134 * (PLDHashTable overhead) > (PLHashTable overhead) 135 * (unused table entry space) > (malloc and .next overhead per entry) + 136 * (buckets overhead) 137 * (1 - alpha) * esize * pow2 > 2 * count + pow2 138 * 139 * Notice that alpha is by definition (count / pow2): 140 * 141 * (1 - alpha) * esize * pow2 > 2 * alpha * pow2 + pow2 142 * (1 - alpha) * esize > 2 * alpha + 1 143 * 144 * esize > (1 + 2 * alpha) / (1 - alpha) 145 * 146 * This assumes both tables must keep keyHash, key, and value for each entry, 147 * where key and value point to separately allocated strings or structures. 148 * If key and value can be combined into one pointer, then the trade-off is: 149 * 150 * esize > (1 + 3 * alpha) / (1 - alpha) 151 * 152 * If the entry value can be a subtype of PLDHashEntryHdr, rather than a type 153 * that must be allocated separately and referenced by an entry.value pointer 154 * member, and provided key's allocation can be fused with its entry's, then 155 * k (the words wasted per entry with chaining) is 4. 156 * 157 * To see these curves, feed gnuplot input like so: 158 * 159 * gnuplot> f(x,k) = (1 + k * x) / (1 - x) 160 * gnuplot> plot [0:.75] f(x,2), f(x,3), f(x,4) 161 * 162 * For k of 2 and a well-loaded table (alpha > .5), esize must be more than 4 163 * words for chaining to be more space-efficient than double hashing. 164 * 165 * Solving for alpha helps us decide when to shrink an underloaded table: 166 * 167 * esize > (1 + k * alpha) / (1 - alpha) 168 * esize - alpha * esize > 1 + k * alpha 169 * esize - 1 > (k + esize) * alpha 170 * (esize - 1) / (k + esize) > alpha 171 * 172 * alpha < (esize - 1) / (esize + k) 173 * 174 * Therefore double hashing should keep alpha >= (esize - 1) / (esize + k), 175 * assuming esize is not too large (in which case, chaining should probably be 176 * used for any alpha). For esize=2 and k=3, we want alpha >= .2; for esize=3 177 * and k=2, we want alpha >= .4. For k=4, esize could be 6, and alpha >= .5 178 * would still obtain. See the PL_DHASH_MIN_ALPHA macro further below. 179 * 180 * The current implementation uses a configurable lower bound on alpha, which 181 * defaults to .25, when deciding to shrink the table (while still respecting 182 * PL_DHASH_MIN_SIZE). 183 * 184 * Note a qualitative difference between chaining and double hashing: under 185 * chaining, entry addresses are stable across table shrinks and grows. With 186 * double hashing, you can't safely hold an entry pointer and use it after an 187 * ADD or REMOVE operation, unless you sample table->generation before adding 188 * or removing, and compare the sample after, dereferencing the entry pointer 189 * only if table->generation has not changed. 190 * 191 * The moral of this story: there is no one-size-fits-all hash table scheme, 192 * but for small table entry size, and assuming entry address stability is not 193 * required, double hashing wins. 194 */ 195struct PLDHashTable { 196 const PLDHashTableOps *ops; /* virtual operations, see below */ 197 void *data; /* ops- and instance-specific data */ 198 PRInt16 hashShift; /* multiplicative hash shift */ 199 uint8 maxAlphaFrac; /* 8-bit fixed point max alpha */ 200 uint8 minAlphaFrac; /* 8-bit fixed point min alpha */ 201 PRUint32 entrySize; /* number of bytes in an entry */ 202 PRUint32 entryCount; /* number of entries in table */ 203 PRUint32 removedCount; /* removed entry sentinels in table */ 204 PRUint32 generation; /* entry storage generation number */ 205 char *entryStore; /* entry storage */ 206#ifdef PL_DHASHMETER 207 struct PLDHashStats { 208 PRUint32 searches; /* total number of table searches */ 209 PRUint32 steps; /* hash chain links traversed */ 210 PRUint32 hits; /* searches that found key */ 211 PRUint32 misses; /* searches that didn't find key */ 212 PRUint32 lookups; /* number of PL_DHASH_LOOKUPs */ 213 PRUint32 addMisses; /* adds that miss, and do work */ 214 PRUint32 addOverRemoved; /* adds that recycled a removed entry */ 215 PRUint32 addHits; /* adds that hit an existing entry */ 216 PRUint32 addFailures; /* out-of-memory during add growth */ 217 PRUint32 removeHits; /* removes that hit, and do work */ 218 PRUint32 removeMisses; /* useless removes that miss */ 219 PRUint32 removeFrees; /* removes that freed entry directly */ 220 PRUint32 removeEnums; /* removes done by Enumerate */ 221 PRUint32 grows; /* table expansions */ 222 PRUint32 shrinks; /* table contractions */ 223 PRUint32 compresses; /* table compressions */ 224 PRUint32 enumShrinks; /* contractions after Enumerate */ 225 } stats; 226#endif 227}; 228 229/* 230 * Size in entries (gross, not net of free and removed sentinels) for table. 231 * We store hashShift rather than sizeLog2 to optimize the collision-free case 232 * in SearchTable. 233 */ 234#define PL_DHASH_TABLE_SIZE(table) PR_BIT(PL_DHASH_BITS - (table)->hashShift) 235 236/* 237 * Table space at entryStore is allocated and freed using these callbacks. 238 * The allocator should return null on error only (not if called with nbytes 239 * equal to 0; but note that pldhash.c code will never call with 0 nbytes). 240 */ 241typedef void * 242(* PR_CALLBACK PLDHashAllocTable)(PLDHashTable *table, PRUint32 nbytes); 243 244typedef void 245(* PR_CALLBACK PLDHashFreeTable) (PLDHashTable *table, void *ptr); 246 247/* 248 * Compute the hash code for a given key to be looked up, added, or removed 249 * from table. A hash code may have any PLDHashNumber value. 250 */ 251typedef PLDHashNumber 252(* PR_CALLBACK PLDHashHashKey) (PLDHashTable *table, const void *key); 253 254/* 255 * Compare the key identifying entry in table with the provided key parameter. 256 * Return PR_TRUE if keys match, PR_FALSE otherwise. 257 */ 258typedef PRBool 259(* PR_CALLBACK PLDHashMatchEntry)(PLDHashTable *table, 260 const PLDHashEntryHdr *entry, 261 const void *key); 262 263/* 264 * Copy the data starting at from to the new entry storage at to. Do not add 265 * reference counts for any strong references in the entry, however, as this 266 * is a "move" operation: the old entry storage at from will be freed without 267 * any reference-decrementing callback shortly. 268 */ 269typedef void 270(* PR_CALLBACK PLDHashMoveEntry)(PLDHashTable *table, 271 const PLDHashEntryHdr *from, 272 PLDHashEntryHdr *to); 273 274/* 275 * Clear the entry and drop any strong references it holds. This callback is 276 * invoked during a PL_DHASH_REMOVE operation (see below for operation codes), 277 * but only if the given key is found in the table. 278 */ 279typedef void 280(* PR_CALLBACK PLDHashClearEntry)(PLDHashTable *table, 281 PLDHashEntryHdr *entry); 282 283/* 284 * Called when a table (whether allocated dynamically by itself, or nested in 285 * a larger structure, or allocated on the stack) is finished. This callback 286 * allows table->ops-specific code to finalize table->data. 287 */ 288typedef void 289(* PR_CALLBACK PLDHashFinalize) (PLDHashTable *table); 290 291/* 292 * Initialize a new entry, apart from keyHash. This function is called when 293 * PL_DHashTableOperate's PL_DHASH_ADD case finds no existing entry for the 294 * given key, and must add a new one. At that point, entry->keyHash is not 295 * set yet, to avoid claiming the last free entry in a severely overloaded 296 * table. 297 */ 298typedef PRBool 299(* PR_CALLBACK PLDHashInitEntry)(PLDHashTable *table, 300 PLDHashEntryHdr *entry, 301 const void *key); 302 303/* 304 * Finally, the "vtable" structure for PLDHashTable. The first eight hooks 305 * must be provided by implementations; they're called unconditionally by the 306 * generic pldhash.c code. Hooks after these may be null. 307 * 308 * Summary of allocation-related hook usage with C++ placement new emphasis: 309 * allocTable Allocate raw bytes with malloc, no ctors run. 310 * freeTable Free raw bytes with free, no dtors run. 311 * initEntry Call placement new using default key-based ctor. 312 * Return PR_TRUE on success, PR_FALSE on error. 313 * moveEntry Call placement new using copy ctor, run dtor on old 314 * entry storage. 315 * clearEntry Run dtor on entry. 316 * finalize Stub unless table->data was initialized and needs to 317 * be finalized. 318 * 319 * Note the reason why initEntry is optional: the default hooks (stubs) clear 320 * entry storage: On successful PL_DHashTableOperate(tbl, key, PL_DHASH_ADD), 321 * the returned entry pointer addresses an entry struct whose keyHash member 322 * has been set non-zero, but all other entry members are still clear (null). 323 * PL_DHASH_ADD callers can test such members to see whether the entry was 324 * newly created by the PL_DHASH_ADD call that just succeeded. If placement 325 * new or similar initialization is required, define an initEntry hook. Of 326 * course, the clearEntry hook must zero or null appropriately. 327 * 328 * XXX assumes 0 is null for pointer types. 329 */ 330struct PLDHashTableOps { 331 /* Mandatory hooks. All implementations must provide these. */ 332 PLDHashAllocTable allocTable; 333 PLDHashFreeTable freeTable; 334 PLDHashHashKey hashKey; 335 PLDHashMatchEntry matchEntry; 336 PLDHashMoveEntry moveEntry; 337 PLDHashClearEntry clearEntry; 338 PLDHashFinalize finalize; 339 340 /* Optional hooks start here. If null, these are not called. */ 341 PLDHashInitEntry initEntry; 342}; 343 344/* 345 * Default implementations for the above ops. 346 */ 347NS_COM_GLUE void * 348PL_DHashAllocTable(PLDHashTable *table, PRUint32 nbytes); 349 350NS_COM_GLUE void 351PL_DHashFreeTable(PLDHashTable *table, void *ptr); 352 353NS_COM_GLUE PLDHashNumber 354PL_DHashStringKey(PLDHashTable *table, const void *key); 355 356/* A minimal entry contains a keyHash header and a void key pointer. */ 357struct PLDHashEntryStub { 358 PLDHashEntryHdr hdr; 359 const void *key; 360}; 361 362NS_COM_GLUE PLDHashNumber 363PL_DHashVoidPtrKeyStub(PLDHashTable *table, const void *key); 364 365NS_COM_GLUE PRBool 366PL_DHashMatchEntryStub(PLDHashTable *table, 367 const PLDHashEntryHdr *entry, 368 const void *key); 369 370NS_COM_GLUE PRBool 371PL_DHashMatchStringKey(PLDHashTable *table, 372 const PLDHashEntryHdr *entry, 373 const void *key); 374 375NS_COM_GLUE void 376PL_DHashMoveEntryStub(PLDHashTable *table, 377 const PLDHashEntryHdr *from, 378 PLDHashEntryHdr *to); 379 380NS_COM_GLUE void 381PL_DHashClearEntryStub(PLDHashTable *table, PLDHashEntryHdr *entry); 382 383NS_COM_GLUE void 384PL_DHashFreeStringKey(PLDHashTable *table, PLDHashEntryHdr *entry); 385 386NS_COM_GLUE void 387PL_DHashFinalizeStub(PLDHashTable *table); 388 389/* 390 * If you use PLDHashEntryStub or a subclass of it as your entry struct, and 391 * if your entries move via memcpy and clear via memset(0), you can use these 392 * stub operations. 393 */ 394NS_COM_GLUE const PLDHashTableOps * 395PL_DHashGetStubOps(void); 396 397/* 398 * Dynamically allocate a new PLDHashTable using malloc, initialize it using 399 * PL_DHashTableInit, and return its address. Return null on malloc failure. 400 * Note that the entry storage at table->entryStore will be allocated using 401 * the ops->allocTable callback. 402 */ 403NS_COM_GLUE PLDHashTable * 404PL_NewDHashTable(const PLDHashTableOps *ops, void *data, PRUint32 entrySize, 405 PRUint32 capacity); 406 407/* 408 * Finalize table's data, free its entry storage (via table->ops->freeTable), 409 * and return the memory starting at table to the malloc heap. 410 */ 411NS_COM_GLUE void 412PL_DHashTableDestroy(PLDHashTable *table); 413 414/* 415 * Initialize table with ops, data, entrySize, and capacity. Capacity is a 416 * guess for the smallest table size at which the table will usually be less 417 * than 75% loaded (the table will grow or shrink as needed; capacity serves 418 * only to avoid inevitable early growth from PL_DHASH_MIN_SIZE). 419 */ 420NS_COM_GLUE PRBool 421PL_DHashTableInit(PLDHashTable *table, const PLDHashTableOps *ops, void *data, 422 PRUint32 entrySize, PRUint32 capacity); 423 424/* 425 * Set maximum and minimum alpha for table. The defaults are 0.75 and .25. 426 * maxAlpha must be in [0.5, 0.9375] for the default PL_DHASH_MIN_SIZE; or if 427 * MinSize=PL_DHASH_MIN_SIZE <= 256, in [0.5, (float)(MinSize-1)/MinSize]; or 428 * else in [0.5, 255.0/256]. minAlpha must be in [0, maxAlpha / 2), so that 429 * we don't shrink on the very next remove after growing a table upon adding 430 * an entry that brings entryCount past maxAlpha * tableSize. 431 */ 432NS_COM_GLUE void 433PL_DHashTableSetAlphaBounds(PLDHashTable *table, 434 float maxAlpha, 435 float minAlpha); 436 437/* 438 * Call this macro with k, the number of pointer-sized words wasted per entry 439 * under chaining, to compute the minimum alpha at which double hashing still 440 * beats chaining. 441 */ 442#define PL_DHASH_MIN_ALPHA(table, k) \ 443 ((float)((table)->entrySize / sizeof(void *) - 1) \ 444 / ((table)->entrySize / sizeof(void *) + (k))) 445 446/* 447 * Default max/min alpha, and macros to compute the value for the |capacity| 448 * parameter to PL_NewDHashTable and PL_DHashTableInit, given default or any 449 * max alpha, such that adding entryCount entries right after initializing the 450 * table will not require a reallocation (so PL_DHASH_ADD can't fail for those 451 * PL_DHashTableOperate calls). 452 * 453 * NB: PL_DHASH_CAP is a helper macro meant for use only in PL_DHASH_CAPACITY. 454 * Don't use it directly! 455 */ 456#define PL_DHASH_DEFAULT_MAX_ALPHA 0.75 457#define PL_DHASH_DEFAULT_MIN_ALPHA 0.25 458 459#define PL_DHASH_CAP(entryCount, maxAlpha) \ 460 ((PRUint32)((double)(entryCount) / (maxAlpha))) 461 462#define PL_DHASH_CAPACITY(entryCount, maxAlpha) \ 463 (PL_DHASH_CAP(entryCount, maxAlpha) + \ 464 (((PL_DHASH_CAP(entryCount, maxAlpha) * (uint8)(0x100 * (maxAlpha))) \ 465 >> 8) < (entryCount))) 466 467#define PL_DHASH_DEFAULT_CAPACITY(entryCount) \ 468 PL_DHASH_CAPACITY(entryCount, PL_DHASH_DEFAULT_MAX_ALPHA) 469 470/* 471 * Finalize table's data, free its entry storage using table->ops->freeTable, 472 * and leave its members unchanged from their last live values (which leaves 473 * pointers dangling). If you want to burn cycles clearing table, it's up to 474 * your code to call memset. 475 */ 476NS_COM_GLUE void 477PL_DHashTableFinish(PLDHashTable *table); 478 479/* 480 * To consolidate keyHash computation and table grow/shrink code, we use a 481 * single entry point for lookup, add, and remove operations. The operation 482 * codes are declared here, along with codes returned by PLDHashEnumerator 483 * functions, which control PL_DHashTableEnumerate's behavior. 484 */ 485typedef enum PLDHashOperator { 486 PL_DHASH_LOOKUP = 0, /* lookup entry */ 487 PL_DHASH_ADD = 1, /* add entry */ 488 PL_DHASH_REMOVE = 2, /* remove entry, or enumerator says remove */ 489 PL_DHASH_NEXT = 0, /* enumerator says continue */ 490 PL_DHASH_STOP = 1 /* enumerator says stop */ 491} PLDHashOperator; 492 493/* 494 * To lookup a key in table, call: 495 * 496 * entry = PL_DHashTableOperate(table, key, PL_DHASH_LOOKUP); 497 * 498 * If PL_DHASH_ENTRY_IS_BUSY(entry) is true, key was found and it identifies 499 * entry. If PL_DHASH_ENTRY_IS_FREE(entry) is true, key was not found. 500 * 501 * To add an entry identified by key to table, call: 502 * 503 * entry = PL_DHashTableOperate(table, key, PL_DHASH_ADD); 504 * 505 * If entry is null upon return, then either the table is severely overloaded, 506 * and memory can't be allocated for entry storage via table->ops->allocTable; 507 * Or if table->ops->initEntry is non-null, the table->ops->initEntry op may 508 * have returned false. 509 * 510 * Otherwise, entry->keyHash has been set so that PL_DHASH_ENTRY_IS_BUSY(entry) 511 * is true, and it is up to the caller to initialize the key and value parts 512 * of the entry sub-type, if they have not been set already (i.e. if entry was 513 * not already in the table, and if the optional initEntry hook was not used). 514 * 515 * To remove an entry identified by key from table, call: 516 * 517 * (void) PL_DHashTableOperate(table, key, PL_DHASH_REMOVE); 518 * 519 * If key's entry is found, it is cleared (via table->ops->clearEntry) and 520 * the entry is marked so that PL_DHASH_ENTRY_IS_FREE(entry). This operation 521 * returns null unconditionally; you should ignore its return value. 522 */ 523NS_COM_GLUE PLDHashEntryHdr * PL_DHASH_FASTCALL 524PL_DHashTableOperate(PLDHashTable *table, const void *key, PLDHashOperator op); 525 526/* 527 * Remove an entry already accessed via LOOKUP or ADD. 528 * 529 * NB: this is a "raw" or low-level routine, intended to be used only where 530 * the inefficiency of a full PL_DHashTableOperate (which rehashes in order 531 * to find the entry given its key) is not tolerable. This function does not 532 * shrink the table if it is underloaded. It does not update stats #ifdef 533 * PL_DHASHMETER, either. 534 */ 535NS_COM_GLUE void 536PL_DHashTableRawRemove(PLDHashTable *table, PLDHashEntryHdr *entry); 537 538/* 539 * Enumerate entries in table using etor: 540 * 541 * count = PL_DHashTableEnumerate(table, etor, arg); 542 * 543 * PL_DHashTableEnumerate calls etor like so: 544 * 545 * op = etor(table, entry, number, arg); 546 * 547 * where number is a zero-based ordinal assigned to live entries according to 548 * their order in table->entryStore. 549 * 550 * The return value, op, is treated as a set of flags. If op is PL_DHASH_NEXT, 551 * then continue enumerating. If op contains PL_DHASH_REMOVE, then clear (via 552 * table->ops->clearEntry) and free entry. Then we check whether op contains 553 * PL_DHASH_STOP; if so, stop enumerating and return the number of live entries 554 * that were enumerated so far. Return the total number of live entries when 555 * enumeration completes normally. 556 * 557 * If etor calls PL_DHashTableOperate on table with op != PL_DHASH_LOOKUP, it 558 * must return PL_DHASH_STOP; otherwise undefined behavior results. 559 * 560 * If any enumerator returns PL_DHASH_REMOVE, table->entryStore may be shrunk 561 * or compressed after enumeration, but before PL_DHashTableEnumerate returns. 562 * Such an enumerator therefore can't safely set aside entry pointers, but an 563 * enumerator that never returns PL_DHASH_REMOVE can set pointers to entries 564 * aside, e.g., to avoid copying live entries into an array of the entry type. 565 * Copying entry pointers is cheaper, and safe so long as the caller of such a 566 * "stable" Enumerate doesn't use the set-aside pointers after any call either 567 * to PL_DHashTableOperate, or to an "unstable" form of Enumerate, which might 568 * grow or shrink entryStore. 569 * 570 * If your enumerator wants to remove certain entries, but set aside pointers 571 * to other entries that it retains, it can use PL_DHashTableRawRemove on the 572 * entries to be removed, returning PL_DHASH_NEXT to skip them. Likewise, if 573 * you want to remove entries, but for some reason you do not want entryStore 574 * to be shrunk or compressed, you can call PL_DHashTableRawRemove safely on 575 * the entry being enumerated, rather than returning PL_DHASH_REMOVE. 576 */ 577typedef PLDHashOperator 578(* PR_CALLBACK PLDHashEnumerator)(PLDHashTable *table, PLDHashEntryHdr *hdr, 579 PRUint32 number, void *arg); 580 581NS_COM_GLUE PRUint32 582PL_DHashTableEnumerate(PLDHashTable *table, PLDHashEnumerator etor, void *arg); 583 584#ifdef PL_DHASHMETER 585#include <stdio.h> 586 587NS_COM_GLUE void 588PL_DHashTableDumpMeter(PLDHashTable *table, PLDHashEnumerator dump, FILE *fp); 589#endif 590 591PR_END_EXTERN_C 592 593#endif /* pldhash_h___ */