.TH "globus_hashtable" 3 "Wed Feb 27 2019" "Version 18.2" "globus_common" \" -*- nroff -*- .ad l .nh .SH NAME globus_hashtable \- Hash Table\&. .SH SYNOPSIS .br .PP .SS "Modules" .in +1c .ti -1c .RI "\fBIterators\fP" .br .RI "Iterators\&. " .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef int(* \fBglobus_hashtable_hash_func_t\fP) (void *key, int limit)" .br .ti -1c .RI "typedef int(* \fBglobus_hashtable_keyeq_func_t\fP) (void *key1, void *key2)" .br .ti -1c .RI "typedef void(* \fBglobus_hashtable_copy_func_t\fP) (void **dest_key, void **dest_datum, void *src_key, void *src_datum)" .br .ti -1c .RI "typedef void(* \fBglobus_hashtable_destructor_func_t\fP) (void *datum)" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBglobus_hashtable_init\fP (globus_hashtable_t *table, int size, \fBglobus_hashtable_hash_func_t\fP hash_func, \fBglobus_hashtable_keyeq_func_t\fP keyeq_func)" .br .RI "Initialize a hash table\&. " .ti -1c .RI "int \fBglobus_hashtable_insert\fP (globus_hashtable_t *table, void *key, void *datum)" .br .RI "Insert a datum into a hash table\&. " .ti -1c .RI "void * \fBglobus_hashtable_update\fP (globus_hashtable_t *table, void *key, void *datum)" .br .RI "Update a hash table mapping\&. " .ti -1c .RI "void * \fBglobus_hashtable_lookup\fP (globus_hashtable_t *table, void *key)" .br .RI "Look up a datum in a hash table\&. " .ti -1c .RI "void * \fBglobus_hashtable_remove\fP (globus_hashtable_t *table, void *key)" .br .RI "Remove a datum from a hash table\&. " .ti -1c .RI "int \fBglobus_hashtable_to_list\fP (globus_hashtable_t *table, \fBglobus_list_t\fP **list)" .br .RI "Create a list of all datums in a hash table\&. " .ti -1c .RI "\fBglobus_bool_t\fP \fBglobus_hashtable_empty\fP (globus_hashtable_t *table)" .br .RI "Test hash table emptiness\&. " .ti -1c .RI "int \fBglobus_hashtable_size\fP (globus_hashtable_t *table)" .br .RI "Hash table size\&. " .ti -1c .RI "int \fBglobus_hashtable_destroy\fP (globus_hashtable_t *table)" .br .RI "Destroy a hash table .PP Destroys a hashtable representation, releasing any resources used to represent the mappings (abandoning any data in the queue)\&. After this call, a hashtable is no longer considered initialized\&. " .ti -1c .RI "int \fBglobus_hashtable_string_hash\fP (void *string, int limit)" .br .RI "Null-terminated string hash function\&. " .ti -1c .RI "int \fBglobus_hashtable_string_keyeq\fP (void *string1, void *string2)" .br .RI "Null-terminated string equality predicate\&. " .ti -1c .RI "int \fBglobus_hashtable_voidp_hash\fP (void *voidp, int limit)" .br .RI "Void pointer hash function\&. " .ti -1c .RI "int \fBglobus_hashtable_voidp_keyeq\fP (void *voidp1, void *voidp2)" .br .RI "Void pointer equality predicate\&. " .ti -1c .RI "int \fBglobus_hashtable_int_hash\fP (void *integer, int limit)" .br .RI "Integer hash function\&. " .ti -1c .RI "int \fBglobus_hashtable_int_keyeq\fP (void *integer1, void *integer2)" .br .RI "Integer equality predicate\&. " .in -1c .SH "Detailed Description" .PP Hash Table\&. The globus_hashtable data type provides an abstract hashtable mapping representation and operations on such mappings\&. These queues can contain arbitrary data in the form of a void pointer for each key and a void pointer for each datum\&. It is the user's responsibility to provide and interpret keys and data of the correct type\&. .SH "Typedef Documentation" .PP .SS "typedef void(* globus_hashtable_copy_func_t) (void **dest_key, void **dest_datum, void *src_key, void *src_datum)" datum copy func .SS "typedef void(* globus_hashtable_destructor_func_t) (void *datum)" Destructor callback for use with globus_hashtable_destroy_all .SS "typedef int(* globus_hashtable_hash_func_t) (void *key, int limit)" An anonymous hash function providing an onto mapping of (key, limit) pairs to integers, where the result integer is in the range [ 0, limit - 1 ] \&. .IP "\(bu" 2 Note that as a proper function, such hash routines must always compute the same result given the same key and limit value\&. .PP \fBParameters:\fP .RS 4 \fIkey\fP Value to map .br \fIlimit\fP Map range limit .RE .PP \fBReturns:\fP .RS 4 Integer hash value of key .RE .PP .PP .SS "typedef int(* globus_hashtable_keyeq_func_t) (void *key1, void *key2)" An anonymous predicate that returns true when the keys are equal and false otherwise\&. Truth and falsity are represented by non-zero and zero (0) integers for use directly in C language conditionals\&. .SH "Function Documentation" .PP .SS "int globus_hashtable_destroy (globus_hashtable_t * table)" .PP Destroy a hash table .PP Destroys a hashtable representation, releasing any resources used to represent the mappings (abandoning any data in the queue)\&. After this call, a hashtable is no longer considered initialized\&. It is an error to destroy a hashtable that is not initialized\&. .PP \fBParameters:\fP .RS 4 \fItable\fP Hash table to destroy\&. .RE .PP .SS "\fBglobus_bool_t\fP globus_hashtable_empty (globus_hashtable_t * table)" .PP Test hash table emptiness\&. .PP \fBReturns:\fP .RS 4 GLOBUS_TRUE if hashtable is empty, GLOBUS_FALSE otherwise .RE .PP .SS "int globus_hashtable_init (globus_hashtable_t * table, int size, \fBglobus_hashtable_hash_func_t\fP hash_func, \fBglobus_hashtable_keyeq_func_t\fP keyeq_func)" .PP Initialize a hash table\&. Initializes a generic chaining hashtable to represent an empty mapping and returns zero, or returns non-zero on failure\&. The size parameter specifies the number of chains with which to represent the mapping\&. This defines the maximum possible number of mappings that can be represented without conflict given a perfect hash, and therefore affects performance as hash conflicts will be resolved by linear chains\&. .PP The hash_func and keyeq_func anonymous functions will be used by the table to manipulate the user's keys\&. .SS "int globus_hashtable_insert (globus_hashtable_t * table, void * key, void * datum)" .PP Insert a datum into a hash table\&. The routine globus_hashtable_insert adds a new mapping to the table, returning zero on success or non-zero on failure\&. Any previous mapping for the same key (where equality is defined by the keyeq_func provided at table initialization) is lost\&. .PP It is an error to call this routine on an uninitialized table\&. .SS "int globus_hashtable_int_hash (void * integer, int limit)" .PP Integer hash function\&. A pathetic hash function for integers, calculating the index as the remainder of dividing the integer by the table size\&. .PP Your pet gerbil could probably design a better hash function for your integer keys, but you might as well use this one if you were going to use modular division anyway\&. .SS "void* globus_hashtable_lookup (globus_hashtable_t * table, void * key)" .PP Look up a datum in a hash table\&. The globus_hashtable_lookup routine returns the datum mapped to the given key in the table, or NULL if the key is not mapped\&. .PP It is an error to call this routine on an uninitialized or empty table\&. .SS "void* globus_hashtable_remove (globus_hashtable_t * table, void * key)" .PP Remove a datum from a hash table\&. The \fBglobus_hashtable_remove()\fP function removes the mapping of key in the table, or does nothing if no such mapping exists\&. .PP It is an error to call this routine on an uninitialized or empty table\&. .SS "int globus_hashtable_size (globus_hashtable_t * table)" .PP Hash table size\&. .PP \fBReturns:\fP .RS 4 Number of entries in hashtable .RE .PP .SS "int globus_hashtable_string_hash (void * string, int limit)" .PP Null-terminated string hash function\&. A decent hash function for null-terminated character arrays\&. .SS "void* globus_hashtable_update (globus_hashtable_t * table, void * key, void * datum)" .PP Update a hash table mapping\&. Update an existing key -> datum association with new values for both, key and datum\&. The old datum is returned\&. If key is non-scalar (eg, string), it should be part of datum so its resources may be recovered\&. If old key does not exist, NULL is returned\&. .SS "int globus_hashtable_voidp_hash (void * voidp, int limit)" .PP Void pointer hash function\&. A decent hash function for void pointers\&. This routine goes to some effort to distribute the information from the address into the hash index by XORing the upper and lower halves of the pointer into one accumulator and calculating the index as the remainder of dividing the accumulator by the table size\&. .SH "Author" .PP Generated automatically by Doxygen for globus_common from the source code\&.