| /* |
| * |
| * Thread-safe Dictionary Using String Identifiers |
| * Copyright 1998-2000 Scott Shambarger (scott@shambarger.net) |
| * |
| * This software is open source. Permission to use, copy, modify, and |
| * distribute this software for any purpose and without fee is hereby granted, |
| * provided that the above copyright notice appear in all copies. No |
| * warranty of any kind is expressed or implied. Use at your own risk. |
| * |
| */ |
| |
| |
| #ifndef __DICT_H_ |
| #define __DICT_H_ |
| |
| __BEGIN_DECLS |
| |
| typedef struct _dictCtx *dictCtx; |
| typedef BOOL (*dictCleanupFunc)(char *id, void *value, void *rock); |
| typedef void (*dictFreeValueFunc)(void *value, void *rock); |
| |
| NEOERR *dictCreate(dictCtx *dict, BOOL threaded, UINT32 root, UINT32 maxLevel, |
| UINT32 flushLimit, BOOL useCase, |
| dictFreeValueFunc freeValue, void *freeRock); |
| /* |
| * Function: dictCreate - create new dictionary. |
| * Description: Returns a dictionary. If <threaded> is true, list is |
| * multi-thread safe. <root>, <maxLevel>, and <flushLimit> |
| * act as for skipNewList() (see skiplist.h) |
| * Input: threaded - true if list should be thread-safe. |
| * root - performance parameter (see above). |
| * maxLevel - performance parameter (see above). |
| * flushLimit - max deleted items to keep cached before |
| * forcing a flush. |
| * useCase - true to be case sensitive in identifiers |
| * freeValue - callback when freeing a value |
| * freeRock - context for freeValue callback |
| * Output: None. |
| * Return: New dictionary, NULL on error. |
| * MT-Level: Safe. |
| */ |
| |
| void dictDestroy(dictCtx dict); |
| /* |
| * Function: dictDestroy - destroy dictionary. |
| * Description: Release all resources used by <dict>. |
| * Input: dict - dictionary to destroy |
| * Output: None. |
| * Return: None. |
| * MT-Level: Safe for unique <dict>. |
| */ |
| |
| BOOL dictRemove(dictCtx dict, const char *id); |
| /* |
| * Function: dictRemove - remove item from dictionary. |
| * Description: Removes item identified by <id> from <dict>. |
| * Input: dict - dictionary to search in. |
| * id - identifier of item to remove. |
| * Output: None. |
| * Return: true if item found, false if not. |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| void *dictSearch(dictCtx dict, const char *id, void **plock); |
| /* |
| * Function: dictSearch - search for value in dictionary. |
| * Description: Searches for <id> in <dict>, and returns value if |
| * found, or NULL if not. If <plock> is non-NULL, then |
| * the lock returned in <plock> will be associated with |
| * the returned value. Until this lock is passed to |
| * dictReleaseLock(), the value will not be passed to the |
| * dictCleanupFunc callback (see dictCleanup()). |
| * Input: dict - dictionary to search in. |
| * id - identifier of item to find. |
| * plock - place for value lock (or NULL). |
| * Output: plock - set to value lock. |
| * Return: Value associated with <id>, or NULL if <id> not found. |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| void *dictNext(dictCtx dict, char **id, void **plock); |
| /* |
| * Function: dictNext - search for next value in dictionary. |
| * Description: Can be used to iterate through values in the dictionary. |
| * The order is the order of the hash of the ids, which |
| * isn't usefully externally. Will return the value if |
| * found, or NULL if not. If <plock> is non-NULL, then |
| * the lock returned in <plock> will be associated with |
| * the returned value. Until this lock is passed to |
| * dictReleaseLock(), the value will not be passed to the |
| * dictCleanupFunc callback (see dictCleanup()). |
| * Input: dict - dictionary to iterate over. |
| * id - pointer to identifier of last item found, or |
| * pointer to NULL to retrieve first. |
| * plock - place for value lock (or NULL). |
| * Output: plock - set to value lock. |
| * id - pointer to id of found value |
| * Return: Value associated with <id>, or NULL if <id> not found. |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| void dictReleaseLock(dictCtx dict, void *lock); |
| /* |
| * Function: dictReleaseLock - release lock on value. |
| * Description: Releases the lock on the value associated with <lock>. Once |
| * the lock is released, the dictCleanupFunc callback can |
| * be called for the value (see dictCleanup()). |
| * Input: dict - dictionary containing value to release. |
| * lock - lock to release. |
| * Output: None. |
| * Return: None. |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| NEOERR *dictSetValue(dictCtx dict, const char *id, void *value); |
| /* |
| * Function: dictSetValue - set/reset an items value. |
| * Description: Updates the <id>/<value> pair into <dict>. |
| * If <id> is not in <dict>, it is created. |
| * Input: dict - dictionary to add pair to. |
| * id - identifier to insert/update |
| * value - value to store (may NOT be NULL) |
| * Output: None. |
| * Return: true if inserted/updated, false if error |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| typedef NEOERR *(*dictNewValueCB)(const char *id, void *rock, void **new_val); |
| typedef NEOERR *(*dictUpdateValueCB)(const char *id, void *value, void *rock); |
| |
| NEOERR *dictModifyValue(dictCtx dict, const char *id, dictNewValueCB new_cb, |
| dictUpdateValueCB update, void *rock); |
| /* |
| * Function: dictModifyValue - create/modify an item. |
| * Description: Finds <id>'s value and calls <update>. If <id> is |
| * not in <dict>, calls <new> to obtain a new value. |
| * Input: dict - dictionary to add pair to. |
| * id - identifier of value |
| * new - function to call to create new value (may be NULL) |
| * update - function to call to modify value (if NULL, the old |
| * value is freed, and <new> is used) |
| * rock - context to pass to <new> or <update>. |
| * Output: None. |
| * Return: true if inserted/updated, false if error |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| void dictCleanup(dictCtx dict, dictCleanupFunc cleanup, void *rock); |
| /* |
| * Function: dictCleanup - cleanup dictionary |
| * Description: Calls <cleanup> for every item in <dict>. If <cleanup> |
| * returns true, then item is removed from <dict>. |
| * Input: dict - dictionary to cleanup |
| * cleanup - cleanup callback |
| * rock - to pass to <cleanup> |
| * Output: None. |
| * Return: None. |
| * MT-Level: Safe if <dict> thread-safe. |
| */ |
| |
| __END_DECLS |
| |
| #endif /* __DICT_H_ */ |