/* * Originally from apache 2.0 * Modifications for general use by */ /* Copyright 2000-2004 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef __HASH_H__ #define __HASH_H__ #ifdef __cplusplus extern "C" { #endif /* * OPTIONAL FEATURES * * Features to define. You need to build both this file and * the corresponding hash.c file with whatever options you set here. * These affect the method signatures, so see the sections below * for the actual options */ /* Keep timestamps for the entries */ #define HASH_TIMESTAMP /* Keep key values internally */ #define HASH_COPYKEYS /* Hash callback functionality */ #define HASH_CALLBACKS /* * ARGUMENT DOCUMENTATION * * ht: The hashtable * key: Pointer to the key value * klen: The length of the key * val: Pointer to the value * hi: A hashtable iterator * stamp: A unix timestamp */ /* ---------------------------------------------------------------------------------- * TYPES */ /* Abstract type for hash tables. */ typedef struct hash_t hash_t; /* Abstract type for scanning hash tables. */ typedef struct hash_index_t hash_index_t; /* ---------------------------------------------------------------------------------- * COPY KEYS MODE * * Use these functions when you want specific length keys, with those * keys stored in the hashtable itself. */ #ifdef HASH_COPYKEYS /* * hash_create : Create a hash table * - returns an allocated hashtable */ hash_t* hash_create(size_t klen); /* * hash_free : Free a hash table */ void hash_free(hash_t* ht); /* * hash_count: Number of values in hash table * - returns the number of entries in hash table */ unsigned int hash_count(hash_t* ht); /* * hash_get: Retrieves a value from the hash table * - returns the value of the entry */ void* hash_get(hash_t* ht, const void* key); /* * hash_set: Set a value in the hash table * - returns 1 if the entry was added properly */ int hash_set(hash_t* ht, const void* key, void* val); /* * hash_rem: Remove a value from the hash table * - returns the value of the removed entry */ void* hash_rem(hash_t* ht, const void* key); /* * hash_first: Start enumerating through the hash table * - returns a hash iterator */ hash_index_t* hash_first(hash_t* ht); /* * hash_next: Enumerate through hash table * - returns the hash iterator or null when no more entries */ hash_index_t* hash_next(hash_index_t* hi); /* * hash_this: While enumerating get current value * - returns the value that the iterator currently points to */ void* hash_this(hash_index_t* hi, const void** key); /* ---------------------------------------------------------------------------------- * VARIABLE KEYS MODE * * Use these functions if you want to use variable length keys or for some * other reason don't want the keys stored in the hash table. */ #else /* * hash_create : Create a hash table * - returns an allocated hashtable */ hash_t* hash_create(); /* * hash_free : Free a hash table */ void hash_free(hash_t* ht); /* * hash_count: Number of values in hash table * - returns the number of entries in hash table */ unsigned int hash_count(hash_t* ht); /* * hash_get: Retrieves a value from the hash table * - returns the value of the entry */ void* hash_get(hash_t* ht, const void* key, size_t klen); /* * hash_set: Set a value in the hash table * - returns 1 if the entry was added properly */ int hash_set(hash_t* ht, const void* key, size_t klen, void* val); /* * hash_rem: Remove a value from the hash table * - returns the value of the removed entry */ void* hash_rem(hash_t* ht, const void* key, size_t klen); /* * hash_first: Start enumerating through the hash table * - returns a hash iterator */ hash_index_t* hash_first(hash_t* ht); /* * hash_next: Enumerate through hash table * - returns the hash iterator or null when no more entries */ hash_index_t* hash_next(hash_index_t* hi); /* * hash_this: While enumerating get current value * - returns the value that the iterator currently points to */ void* hash_this(hash_index_t* hi, const void** key, size_t* klen); /* * This can be passed as 'klen' in any of the above functions to indicate * a string-valued key, and have hash compute the length automatically. */ #define HASH_KEY_STRING (-1) #endif /* ---------------------------------------------------------------------------------- * TIMESTAMP FUNCTIONALITY * * Use these functions to include functionality which tracks the time * each key was added or changed. This is useful for caches. Use these * functions in addition to one of the above 'key' modes. */ #ifdef HASH_TIMESTAMP /* * hash_purge: Purge entries before a certain timestamp * - returns the number of entries purged */ int hash_purge(hash_t* ht, time_t stamp); /* * hash_touch: Touch an entry to make it's timestamp current */ #ifdef HASH_COPYKEYS void hash_touch(hash_t* ht, const void* key); #else void hash_touch(hash_t* ht, const void* key, size_t* klen); #endif /* * hash_bump: Bumps the oldest entry out */ int hash_bump(hash_t* ht); #endif /* ---------------------------------------------------------------------------------- * CALLBACK FUNCTIONALITY * * Use these functions to replace certain calls (malloc, free etc...) as * well as to get callbacks when an item is discarded. */ #ifdef HASH_CALLBACKS typedef void* (*hash_falloc)(void* arg, size_t len); typedef void (*hash_ffree)(void* arg, void* ptr); typedef struct hash_memory_calls { hash_falloc f_alloc; hash_ffree f_free; void* arg; } hash_memory_calls_t; /* Set the global memory calls */ void hash_set_memory_calls(hash_memory_calls_t* hmc); typedef void (*hash_ffreeval)(void* arg, void* val); typedef struct hash_table_calls { hash_ffreeval f_freeval; void* arg; } hash_table_calls_t; /* Set the per table free value call */ void hash_set_table_calls(hash_t* ht, hash_table_calls_t* htc); #endif #ifdef __cplusplus } #endif #endif /* __HASH_H__ */