Data Structures | Defines | Typedefs | Functions

sst/elements/genericProc/programs/libcprops/hashtable.h File Reference

generic synchronized hashtable. More...

#include "common.h"
#include "collection.h"
#include "config.h"

Go to the source code of this file.

Data Structures

struct  _cp_hashtable_entry
 Internal object that implements a key, value pair plus linked list. More...
struct  _cp_hashtable
 data structure of generic synchronized cp_hashtable More...

Defines

#define HASH_SEED   1000000001L
 1000000001 is a prime.
#define CP_HASHTABLE_DEFAULT_MIN_FILL_FACTOR   5
#define CP_HASHTABLE_DEFAULT_MAX_FILL_FACTOR   70
#define cp_hashtable_create_by_mode(mode, size_hint, cp_hashfn, compare_fn)   cp_hashtable_create_by_option((mode), (size_hint), (cp_hashfn), (compare_fn), NULL, NULL, NULL, NULL)
 creates a new cp_hashtable with the specified mode.
#define cp_hashtable_rdlock(table)   cp_hashtable_lock((table), COLLECTION_LOCK_READ)
 macro to get a read lock on the table
#define cp_hashtable_wrlock(table)   cp_hashtable_lock((table), COLLECTION_LOCK_WRITE)
 macro to get a write lock on the table
#define cp_hashtable_is_empty(table)   (cp_hashtable_count(table) == 0)
 Check if the collection is empty.

Typedefs

typedef unsigned long(* cp_hashfunction )(void *)
 the hash function takes (void *) and returns unsigned long.
typedef CPROPS_DLL struct
_cp_hashtable_entry 
cp_hashtable_entry
 Internal object that implements a key, value pair plus linked list.
typedef CPROPS_DLL struct
_cp_hashtable 
cp_hashtable
 data structure of generic synchronized cp_hashtable

Functions

unsigned long cp_hash_int (void *key)
 hash function for int keys
int cp_hash_compare_int (void *key1, void *key2)
 comparator for int keys
unsigned long cp_hash_long (void *key)
 hash function for long keys
int cp_hash_compare_long (void *key1, void *key2)
 comparator for long keys
unsigned long cp_hash_addr (void *addr)
 hash function for pointer keys
int cp_hash_compare_addr (void *key1, void *key2)
 comparator for pointer keys
unsigned long cp_hash_string (void *key)
 hash function for (char *) keys
unsigned long cp_hash_istring (void *key)
 case insensitive hash function for (char *) keys
void * cp_hash_copy_string (void *element)
 copy function for cp_string copy tables
int cp_hash_compare_string (void *key1, void *key2)
 comparator for (char *) keys
int cp_hash_compare_istring (void *key1, void *key2)
 comparator for (char *) keys
cp_hashtablecp_hashtable_create (unsigned long size_hint, cp_hashfunction hashfn, cp_compare_fn compare_fn)
 creates a new cp_hashtable.
cp_hashtablecp_hashtable_create_copy_mode (unsigned long size_hint, cp_hashfunction hash_fn, cp_compare_fn compare_fn, cp_copy_fn copy_key, cp_destructor_fn free_key, cp_copy_fn copy_value, cp_destructor_fn free_value)
 creates a new cp_hashtable with COLLECTION_MODE_DEEP | COLLECTION_MODE_COPY.
cp_hashtablecp_hashtable_create_by_option (int mode, unsigned long size_hint, cp_hashfunction hash_fn, cp_compare_fn compare_fn, cp_copy_fn copy_key, cp_destructor_fn free_key, cp_copy_fn copy_value, cp_destructor_fn free_value)
 create a new table, fully specifying all parameters.
void cp_hashtable_destroy (cp_hashtable *table)
 deletes a cp_hashtable according to the current mode settings
void cp_hashtable_destroy_shallow (cp_hashtable *table)
 deletes a cp_hashtable.
void cp_hashtable_destroy_deep (cp_hashtable *table)
 deletes a cp_hashtable.
void cp_hashtable_destroy_custom (cp_hashtable *table, cp_destructor_fn dk, cp_destructor_fn dv)
 Deep destroy with custom destructors for keys and values.
int cp_hashtable_lock (cp_hashtable *table, int type)
 by default the get, put and remove functions as well as set and unset mode perform their own locking.
int cp_hashtable_unlock (cp_hashtable *table)
 unlock the table
int cp_hashtable_get_mode (cp_hashtable *table)
 returns the current operation mode.
int cp_hashtable_set_mode (cp_hashtable *table, int mode)
 set the operation mode as a bit set of the following options:
int cp_hashtable_unset_mode (cp_hashtable *table, int mode)
 unset the mode bits defined by mode
int cp_hashtable_set_min_size (cp_hashtable *table, int min_size)
 the internal table will not be resized to less than min_size
int cp_hashtable_set_max_fill_factor (cp_hashtable *table, int fill_factor)
 a resize is triggered when the table contains more items than table_size * fill_factor / 100
int cp_hashtable_set_min_fill_factor (cp_hashtable *table, int fill_factor)
 a resize is triggered when the table contains less items than table_size * fill_factor / 100
void * cp_hashtable_get (cp_hashtable *table, void *key)
 attempts to retrieve the value assigned to the key 'key'.
void * cp_hashtable_get_by_option (cp_hashtable *table, void *key, int option)
 Retrieves the value by key.
void * cp_hashtable_put_by_option (cp_hashtable *table, void *key, void *value, int mode)
 Internal put method.
void * cp_hashtable_put (cp_hashtable *table, void *key, void *value)
 the key 'key' will be assigned to the value 'value'.
void * cp_hashtable_put_safe (cp_hashtable *table, void *key, void *value)
 same as cp_hashtable_put(table, key, value) except that an old value is released if it exists.
void * cp_hashtable_put_copy (cp_hashtable *table, void *key, void *value)
 same as cp_hashtable_put(table, key, value) except that it inserts a copy of the key and the value object.
void * cp_hashtable_remove (cp_hashtable *table, void *key)
 Attempts to remove the mapping for key from the table.
int cp_hashtable_remove_all (cp_hashtable *table)
 remove all entries with current mode
int cp_hashtable_remove_deep (cp_hashtable *table, void *key)
 Remove with COLLECTION_MODE_DEEP set.
int cp_hashtable_contains (cp_hashtable *table, void *key)
 Check if there is an entry with matching key.
void ** cp_hashtable_get_keys (cp_hashtable *table)
 get an array containing all keys mapped in table table.
void ** cp_hashtable_get_values (cp_hashtable *table)
 get an array containing all values in the table.
unsigned long cp_hashtable_count (cp_hashtable *table)
 Get the number of entries in the collection.
unsigned long cp_hashtable_choose_size (unsigned long size_request)

Detailed Description

generic synchronized hashtable.

Here is an example of using a cp_hashtable to create a lookup for 'bar' items using 'foo' keys:

 unsigned long foo_hash_code(void *fooptr) 
 {
     return ((foo *) fooptr)->id; 
 }

 // compare function
 int foo_compare(void *f1, void *f2)
 {
     return ((foo *) f1)->id != ((foo *) f2)->id;
 }

 ...

     cp_hashtable *t;
     foo *foo1, *f;
     bar *bar1, *bar2;

     t = cp_hashtable_create(10, foo_hash_code, foo_compare);
     if (t == NULL) 
     {
         perror("can\'t create cp_hashtable");
         exit(1);
     }

     cp_hashtable_put(foo1, bar1, t);

     ...
     f = foo_create(...);
     ...

     if ((bar2 = (bar *) cp_hashtable_get(f, t))) 
         printf("%s maps to %s\n", foo_get_name(f), bar_get_name(bar2));
     else 
         printf("%s is not mapped\n", foo_get_name(f));

     ...

     cp_hashtable_destroy(t);
 

Note the strcmp like semantics of the compare function. The comparison should return 0 for identical keys.

See also:
hash.h (util.collection) for function prototypes and convenience functions.
cp_hashtable_create, cp_hashtable_destroy, cp_hashtable_destroy_deep, cp_hashtable_put, cp_hashtable_get, cp_hashtable_contains, cp_hashtable_remove_deep