#ifndef __HASHTABLE_CWC22_H__
#define __HASHTABLE_CWC22_H__

#include <unistd.h>

struct shmht;

/*! \mainpage lib_shmht
 *
 * \section Introduction
 *
 * The lib_shmht is a full-functionall hashtable implementation in shared memory.<BR>
 * This library is designed for high-performace caches, but it can be used for
 * many pourpouses. <BR>
 * Design principles of the lib_shmht: <BR>
 * <b>no-reallocation</b> of the shared memory. So, the HT can't grow in size from it's creation, but you
 * can define the % of older entries that can be erased when a element has not enought
 * space.<BR>
 * <b>concurrency</b>: The accesses are controlled by a semaphore R/W lock implemntation, so not concurrency
 * problem is possible.<BR>
 * <b>performance</b>: The performance is the main target of this implementation.<BR>
 *
 * It has the next <b>limitations</b>: <BR>
 *  * Key size limited by compiling time.<BR>
 *  * The erased elements are the oldests, not the less used. This is to don't write (and lock the entire ht)
 * in all the reads.<BR>
 *
 * Please, check the design file if you want more specifical data.
 * 
 */


/*!   
 * @name                    shmht_hashtable
 * @param   name            Name of the HashTable.
 * @param   number          Number of records.
 * @param   size            Size of each record.
 * @param   hashfunction    function for hashing keys.
 * @param   key_eq_fn       function for determining key equality
 * @return                  newly created hashtable or NULL on failure
 *
 * This function, takes the existing shared memory, or creates if it does not
 * exists.
 * The name is the primary key of the shared memory hash table. If it exists, 
 * the create_hashtable will asociate with the apropiate shared memory.
 *
 */

struct shmht *create_shmht(char *name,
				unsigned int number,
				size_t size,
				unsigned int (*hashfunction) (void *),
				int (*key_eq_fn) (void *, void *));

/*!   
 * @name        shmht_insert
 * @param   h   the hashtable to insert into
 * @param   k   the key - hashtable claims ownership and will free on removal
 * @param   v   the value - does not claim ownership
 * @return      > zero for successful insertion, else for error.
 *
 * This function does not check for repeated insertions with a duplicate key.
 * The value returned when using a duplicate key is undefined.
 * If in doubt, remove before insert.
 * The size of this hashtable is fixed, so if the hashtable is full, the insert
 * will fail.
 */

int
shmht_insert (struct shmht *h, void *k, size_t key_size, void *v,
				  size_t value_size);


/*!   
 * @name        shmht_search
 * @param   h   the hashtable to search
 * @param   k   the key to search for  - does not claim ownership
 * @param key_size Size of the key.
 * @param returned_size [out], the size of the returned value.
 * @return      the value associated with the key, or NULL if none found
 * 
 * You should be careful, beacause, this function returns a pointer to the 
 * shared memory area. DO NOT FREE THIS POINTER!
 */

void *shmht_search (struct shmht *h, void *k, size_t key_size,
						size_t * returned_size);


/*!   
 * @name        shmht_remove
 * @param   h   the hashtable to remove the item from
 * @param   k   the key to search for  - does not claim ownership
 * @param returned_size  [out] returns the size of the returned void *.
 * @return      the number of items removed.
 */

int shmht_remove (struct shmht *h, void *k, size_t key_size);



/*!   
 * @name        shmht_count
 * @param   h   the hashtable
 * @return      the number of items stored in the hashtable, -1 if something
 *              nasty happens.
 */
int shmht_count (struct shmht *h);


/*!   
 * @name        shmht_flush
 * @param   h   the hashtable
 * @return      0 if not problem, <0 if error.
 */

int shmht_flush (struct shmht *h);

/*!
 * @name        shmht_remove_older_entries
 * @param   h   the hashtable
 * @param   p   the % of older values to erase
 * @return      The number of deleted entries.
 */

int shmht_remove_older_entries (struct shmht *h, int p);

/*!   
 * @name        shmht_destroy
 * @param   h   the hashtable
 * 
 * Be careful with this operation, beacause all the processes that are currently
 * using the shared memory hash table will fail (it deletes the shared memory and
 * the semaphores used as mutex). 
 * If you have any doubt, use the hashtable_flush, instead of this function.
 */

int shmht_destroy (struct shmht *h);

#endif /* __HASHTABLE_CWC22_H__ */