1 /* 2 * 3 * Thread-safe Dictionary Using String Identifiers 4 * Copyright 1998-2000 Scott Shambarger (scott@shambarger.net) 5 * 6 * This software is open source. Permission to use, copy, modify, and 7 * distribute this software for any purpose and without fee is hereby granted, 8 * provided that the above copyright notice appear in all copies. No 9 * warranty of any kind is expressed or implied. Use at your own risk. 10 * 11 */ 12 13 14 #ifndef __DICT_H_ 15 #define __DICT_H_ 16 17 __BEGIN_DECLS 18 19 typedef struct _dictCtx *dictCtx; 20 typedef BOOL (*dictCleanupFunc)(char *id, void *value, void *rock); 21 typedef void (*dictFreeValueFunc)(void *value, void *rock); 22 23 NEOERR *dictCreate(dictCtx *dict, BOOL threaded, UINT32 root, UINT32 maxLevel, 24 UINT32 flushLimit, BOOL useCase, 25 dictFreeValueFunc freeValue, void *freeRock); 26 /* 27 * Function: dictCreate - create new dictionary. 28 * Description: Returns a dictionary. If <threaded> is true, list is 29 * multi-thread safe. <root>, <maxLevel>, and <flushLimit> 30 * act as for skipNewList() (see skiplist.h) 31 * Input: threaded - true if list should be thread-safe. 32 * root - performance parameter (see above). 33 * maxLevel - performance parameter (see above). 34 * flushLimit - max deleted items to keep cached before 35 * forcing a flush. 36 * useCase - true to be case sensitive in identifiers 37 * freeValue - callback when freeing a value 38 * freeRock - context for freeValue callback 39 * Output: None. 40 * Return: New dictionary, NULL on error. 41 * MT-Level: Safe. 42 */ 43 44 void dictDestroy(dictCtx dict); 45 /* 46 * Function: dictDestroy - destroy dictionary. 47 * Description: Release all resources used by <dict>. 48 * Input: dict - dictionary to destroy 49 * Output: None. 50 * Return: None. 51 * MT-Level: Safe for unique <dict>. 52 */ 53 54 BOOL dictRemove(dictCtx dict, const char *id); 55 /* 56 * Function: dictRemove - remove item from dictionary. 57 * Description: Removes item identified by <id> from <dict>. 58 * Input: dict - dictionary to search in. 59 * id - identifier of item to remove. 60 * Output: None. 61 * Return: true if item found, false if not. 62 * MT-Level: Safe if <dict> thread-safe. 63 */ 64 65 void *dictSearch(dictCtx dict, const char *id, void **plock); 66 /* 67 * Function: dictSearch - search for value in dictionary. 68 * Description: Searches for <id> in <dict>, and returns value if 69 * found, or NULL if not. If <plock> is non-NULL, then 70 * the lock returned in <plock> will be associated with 71 * the returned value. Until this lock is passed to 72 * dictReleaseLock(), the value will not be passed to the 73 * dictCleanupFunc callback (see dictCleanup()). 74 * Input: dict - dictionary to search in. 75 * id - identifier of item to find. 76 * plock - place for value lock (or NULL). 77 * Output: plock - set to value lock. 78 * Return: Value associated with <id>, or NULL if <id> not found. 79 * MT-Level: Safe if <dict> thread-safe. 80 */ 81 82 void *dictNext(dictCtx dict, char **id, void **plock); 83 /* 84 * Function: dictNext - search for next value in dictionary. 85 * Description: Can be used to iterate through values in the dictionary. 86 * The order is the order of the hash of the ids, which 87 * isn't usefully externally. Will return the value if 88 * found, or NULL if not. If <plock> is non-NULL, then 89 * the lock returned in <plock> will be associated with 90 * the returned value. Until this lock is passed to 91 * dictReleaseLock(), the value will not be passed to the 92 * dictCleanupFunc callback (see dictCleanup()). 93 * Input: dict - dictionary to iterate over. 94 * id - pointer to identifier of last item found, or 95 * pointer to NULL to retrieve first. 96 * plock - place for value lock (or NULL). 97 * Output: plock - set to value lock. 98 * id - pointer to id of found value 99 * Return: Value associated with <id>, or NULL if <id> not found. 100 * MT-Level: Safe if <dict> thread-safe. 101 */ 102 103 void dictReleaseLock(dictCtx dict, void *lock); 104 /* 105 * Function: dictReleaseLock - release lock on value. 106 * Description: Releases the lock on the value associated with <lock>. Once 107 * the lock is released, the dictCleanupFunc callback can 108 * be called for the value (see dictCleanup()). 109 * Input: dict - dictionary containing value to release. 110 * lock - lock to release. 111 * Output: None. 112 * Return: None. 113 * MT-Level: Safe if <dict> thread-safe. 114 */ 115 116 NEOERR *dictSetValue(dictCtx dict, const char *id, void *value); 117 /* 118 * Function: dictSetValue - set/reset an items value. 119 * Description: Updates the <id>/<value> pair into <dict>. 120 * If <id> is not in <dict>, it is created. 121 * Input: dict - dictionary to add pair to. 122 * id - identifier to insert/update 123 * value - value to store (may NOT be NULL) 124 * Output: None. 125 * Return: true if inserted/updated, false if error 126 * MT-Level: Safe if <dict> thread-safe. 127 */ 128 129 typedef NEOERR *(*dictNewValueCB)(const char *id, void *rock, void **new_val); 130 typedef NEOERR *(*dictUpdateValueCB)(const char *id, void *value, void *rock); 131 132 NEOERR *dictModifyValue(dictCtx dict, const char *id, dictNewValueCB new_cb, 133 dictUpdateValueCB update, void *rock); 134 /* 135 * Function: dictModifyValue - create/modify an item. 136 * Description: Finds <id>'s value and calls <update>. If <id> is 137 * not in <dict>, calls <new> to obtain a new value. 138 * Input: dict - dictionary to add pair to. 139 * id - identifier of value 140 * new - function to call to create new value (may be NULL) 141 * update - function to call to modify value (if NULL, the old 142 * value is freed, and <new> is used) 143 * rock - context to pass to <new> or <update>. 144 * Output: None. 145 * Return: true if inserted/updated, false if error 146 * MT-Level: Safe if <dict> thread-safe. 147 */ 148 149 void dictCleanup(dictCtx dict, dictCleanupFunc cleanup, void *rock); 150 /* 151 * Function: dictCleanup - cleanup dictionary 152 * Description: Calls <cleanup> for every item in <dict>. If <cleanup> 153 * returns true, then item is removed from <dict>. 154 * Input: dict - dictionary to cleanup 155 * cleanup - cleanup callback 156 * rock - to pass to <cleanup> 157 * Output: None. 158 * Return: None. 159 * MT-Level: Safe if <dict> thread-safe. 160 */ 161 162 __END_DECLS 163 164 #endif /* __DICT_H_ */ 165