/* 
 *
 * 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_ */