Main Page Modules Data Structures File List Data Fields Globals Related Pages
gm_hash.c File Reference
#include "gm_call_trace.h"
#include "gm_compiler.h"
#include "gm_crc32.h"
#include "gm_debug.h"
#include "gm_internal.h"
Data Structures |
struct | gm_hash_entry |
struct | gm_hash_segment |
struct | gm_hash |
Typedefs |
typedef gm_hash_entry | gm_hash_entry_t |
typedef gm_hash_segment | gm_hash_segment_t |
typedef gm_hash | gm_hash_t |
Functions |
GM_ENTRY_POINT struct gm_hash * | gm_create_hash (long(*gm_user_compare)(void *key1, void *key2), unsigned long(*gm_user_hash)(void *key), gm_size_t key_len, gm_size_t data_len, gm_size_t min_cnt, int flags) |
GM_ENTRY_POINT void | gm_destroy_hash (struct gm_hash *hash) |
GM_ENTRY_POINT void * | gm_hash_remove (gm_hash_t *hash, void *key) |
GM_ENTRY_POINT void * | gm_hash_find (gm_hash_t *hash, void *key) |
GM_ENTRY_POINT void | gm_hash_rekey (gm_hash_t *hash, void *old_key, void *new_key) |
GM_ENTRY_POINT gm_status_t | gm_hash_insert (gm_hash_t *hash, void *key, void *data) |
GM_ENTRY_POINT long | gm_hash_compare_strings (void *key1, void *key2) |
GM_ENTRY_POINT unsigned long | gm_hash_hash_string (void *key) |
GM_ENTRY_POINT long | gm_hash_compare_longs (void *key1, void *key2) |
GM_ENTRY_POINT unsigned long | gm_hash_hash_long (void *key) |
GM_ENTRY_POINT long | gm_hash_compare_ints (void *key1, void *key2) |
GM_ENTRY_POINT unsigned long | gm_hash_hash_int (void *key) |
GM_ENTRY_POINT long | gm_hash_compare_ptrs (void *key1, void *key2) |
GM_ENTRY_POINT unsigned long | gm_hash_hash_ptr (void *key) |
Detailed Description
This file contains the GM API functions gm_create_hash(), gm_destroy_hash(), gm_hash_remove(), gm_hash_find(), gm_hash_insert(), gm_hash_rekey(), gm_hash_compare_strings(), gm_hash_hash_string(), gm_hash_compare_longs(), gm_hash_hash_long(), gm_hash_compare_ints(), gm_hash_hash_int(), gm_hash_compare_ptr(), gm_hash_hash_ptr().
This module implements a generic hash table. It uses lookaside lists to ensure efficient memory allocation in the kernel.
GM implements a generic hash table with a flexible interface. This module can automatically manage storage of fixed-size keys and/or data, or can allow the client to manage storage for keys and/or data. It allows the client to specify arbitrary hashing and comparison functions.
For example,
hash = gm_create_hash (gm_hash_compare_strings, gm_hash_hash_string,
0, 0, 0, 0);
creates a hash table that uses null-terminated character string keys residing in client-managed storage, and returns pointers to data in client-managed storage. In this case, all pointers to hash keys and data passed by GM to the client will be the same as the pointers passed by the client to GM.
As another example,
hash = gm_create_hash (gm_hash_compare_ints, gm_hash_hash_int,
sizeof (int), sizeof (struct my_big_struct),
100, 0);
creates a hash table that uses `ints' as keys and returns pointers to copies of the inserted structures. All storage for the keys and data is automatically managed by the hash table. In this case, all pointers to hash keys and data passed by GM to the client will point to GM-managed buffers. This function also preallocates enough storage for 100 hash entries, guaranteeing that at least 100 key/data pairs can be inserted in the table if the hash table creation succeeds.
The automatic storage management option of GM not only is convenient, but also is extremely space efficient for keys and data no larger than a pointer, because when keys and data are no larger than a pointer, GM automatically stores them in the space reserved for the pointer to the key or data, rather than allocating a separate buffer.
Note that all keys and data buffers are referred to by pointers, not by value. This allows keys and data buffers of arbitrary size to be used. As a special (but common) case, however, one may wish to use pointers as keys directly, rather than use what they point to. In this special case, use the following initialization, and pass the keys (pointers) directly to the API, rather than the usual references to the keys.
hash = gm_create_hash (gm_hash_compare_ptrs, gm_hash_hash_ptr,
0, DATA_LEN, MIN_CNT, FLAGS);
While it is possible to specify a KEY_LEN of `sizeof (void *)' during initialization and treat pointer keys just like any other keys, the API above is more efficient, more convenient, and completely architecture independent.
Typedef Documentation
|
Structure representing a segment of allocated hash table bins. To double the size of the hash table, we allocate a new segment with just enough bins to double the number of bins in the hash table an prepend it to the list of hash segments. This way, we don't have to double-buffer the hash table while growing it, and we can grow the table closer to the limits of available memory. While we sometimes have to walk the O(log(N))-segment list to find a bin, the average lookup only looks at O(2) segments, so operations are still constant-average-time as expected for hash tables. |
|
The state of a GM hash table, referenced by the client only using opaque pointers. |
Function Documentation
GM_ENTRY_POINT struct gm_hash* gm_create_hash |
( |
long(* |
gm_user_compare)(void *key1, void *key2), |
|
|
unsigned long(* |
gm_user_hash)(void *key), |
|
|
gm_size_t |
key_len, |
|
|
gm_size_t |
data_len, |
|
|
gm_size_t |
min_cnt, |
|
|
int |
flags |
|
) |
|
|
|
gm_create_hash() returns a newly-created `gm_hash' structure or `0' if the hash table could not be created. -
Return values:
-
-
Parameters:
-
gm_user_compare |
(IN) The function used to compare keys and may be any of gm_hash_compare_ints, gm_hash_compare_longs, gm_hash_compare_ptrs, gm_hash_compare_strings, or may be a client-defined function. |
gm_user_hash |
(IN) The function to be used to hash keys and may be any of gm_hash_hash_int, gm_hash_hash_long, gm_hash_hash_ptr, gm_hash_hash_string, or may be a client-defined function. |
key_len |
(IN) Specifies the length of the keys to be used for the hash table, or `0' if the keys should not be copied into GM-managed buffers. |
data_len |
(IN) Specifies the length of the data to be stored in the hash table, or `0' if the data should not be copied into GM-managed buffers. |
min_cnt |
(IN) Specifies the number of entries for which storage should be preallocated. |
flags |
(IN) Should be `0' because no flags are currently defined. |
-
See also:
-
gm_destroy_hash
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
GM_ENTRY_POINT void gm_destroy_hash |
( |
struct gm_hash * |
hash |
) |
|
|
|
gm_destroy_hash() frees all resources associated with the hash table, except for any client-allocated buffers. -
Parameters:
-
hash |
(IN) Handle to the hash table. |
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
GM_ENTRY_POINT void* gm_hash_remove |
( |
gm_hash_t * |
hash, |
|
|
void * |
key |
|
) |
|
|
|
gm_hash_remove() removes an entry associated with KEY from the hash table HASH and returns a pointer to the data associated with the key, or `0' if no match exists. If the data resides in a GM-managed buffer, it is only guaranteed to be valid until the next operation on the hash table. -
Parameters:
-
hash |
(IN) Pointer to the hash table. |
key |
(IN) The key for the hash table. |
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
GM_ENTRY_POINT void* gm_hash_find |
( |
gm_hash_t * |
hash, |
|
|
void * |
key |
|
) |
|
|
|
gm_hash_find() finds an entry associated with KEY from the hash table HASH and returns a pointer to the data associated with the key, or `0' if no match exists. -
Parameters:
-
hash |
(IN) Pointer to the hash table. |
key |
(IN) The key for the hash table. |
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
GM_ENTRY_POINT void gm_hash_rekey |
( |
gm_hash_t * |
hash, |
|
|
void * |
old_key, |
|
|
void * |
new_key |
|
) |
|
|
|
gm_hash_rekey() finds each entry with key OLD_KEY and changes the key used to store the data to NEW_KEY. This call is guaranteed to succeed. -
Parameters:
-
hash |
(IN) Pointer to the hash table. |
old_key |
(IN) The previous key for the hash table. |
new_key |
(IN) The new key for the hash table. |
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
|
gm_hash_insert() stores the association of KEY and DATA in the hash table HASH. The key `*'KEY (or data `*'DATA) is copied into the hash table unless the table was initialized with a KEY_LEN (or DATA_LEN) of 0. -
Return values:
-
GM_SUCCESS |
Operation completed successfully. |
-
Parameters:
-
hash |
(IN) Pointer to the hash table. |
key |
(IN) The key for the hash table. |
data |
(IN) Data to be inserted. |
-
Author:
-
Glenn Brown
-
Version:
-
GM_API_VERSION (as defined in gm.h)
|
GM_ENTRY_POINT long gm_hash_compare_strings |
( |
void * |
key1, |
|
|
void * |
key2 |
|
) |
|
|
GM_ENTRY_POINT unsigned long gm_hash_hash_string |
( |
void * |
key |
) |
|
|
GM_ENTRY_POINT long gm_hash_compare_longs |
( |
void * |
key1, |
|
|
void * |
key2 |
|
) |
|
|
GM_ENTRY_POINT unsigned long gm_hash_hash_long |
( |
void * |
key |
) |
|
|
GM_ENTRY_POINT long gm_hash_compare_ints |
( |
void * |
key1, |
|
|
void * |
key2 |
|
) |
|
|
GM_ENTRY_POINT unsigned long gm_hash_hash_int |
( |
void * |
key |
) |
|
|
GM_ENTRY_POINT long gm_hash_compare_ptrs |
( |
void * |
key1, |
|
|
void * |
key2 |
|
) |
|
|
GM_ENTRY_POINT unsigned long gm_hash_hash_ptr |
( |
void * |
key |
) |
|
|
Generated on Mon Nov 3 15:39:26 2003 for GM by
1.2.15