path: root/common/hash.h

/*
 * Originally from apache 2.0
 * Modifications for general use by <nielsen@memberwebs.com>
 */

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