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_hashgm_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

typedef struct gm_hash_entry gm_hash_entry_t
 

A hash table entry.

typedef struct gm_hash_segment gm_hash_segment_t
 

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.

typedef struct gm_hash gm_hash_t
 

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:
gm_hash  Handle to the hash table.
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_ENTRY_POINT gm_status_t gm_hash_insert gm_hash_t   hash,
void *    key,
void *    data
 

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_hash_compare_strings() is the function used to compare two strings.

Return values:
long 
Parameters:
key1  (IN) The key for the first string.
key2  (IN) The key for the second string.
See also:
gm_hash_compare_ints gm_hash_compare_longs gm_hash_compare_ptrs
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT unsigned long gm_hash_hash_string void *    key
 

gm_hash_hash_string() is the function used to hash keys.

Return values:
long 
Parameters:
key  (IN) The key for the string in the hash table.
See also:
gm_hash_compare_string gm_hash_hash_int gm_hash_hash_long gm_hash_hash_ptr
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT long gm_hash_compare_longs void *    key1,
void *    key2
 

gm_hash_compare_longs() is the function used to compare two longs.

Return values:
long 
Parameters:
key1  (IN)
key2  (IN)
See also:
gm_hash_compare_ints gm_hash_compare_strings gm_hash_compare_ptrs
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT unsigned long gm_hash_hash_long void *    key
 

gm_hash_hash_long() is the function used to hash keys.

Return values:
long 
Parameters:
key  (IN)
See also:
gm_hash_compare_long gm_hash_hash_int gm_hash_hash_string gm_hash_hash_ptr
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT long gm_hash_compare_ints void *    key1,
void *    key2
 

gm_hash_compare_ints() is the function used to compare two ints.

Return values:
long 
Parameters:
key1  (IN) The key for the first int.
key2  (IN) The key for the second int.
See also:
gm_hash_compare_longs gm_hash_compare_strings gm_hash_compare_ptrs
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT unsigned long gm_hash_hash_int void *    key
 

gm_hash_hash_int() is the function used to hash keys.

Return values:
long 
Parameters:
key  (IN)
See also:
gm_hash_compare_int gm_hash_hash_ptr gm_hash_hash_long gm_hash_hash_string
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT long gm_hash_compare_ptrs void *    key1,
void *    key2
 

gm_hash_compare_ptrs() is the function used to compare two ptrs.

Return values:
long 
Parameters:
key1  (IN) The key for the first ptr.
key2  (IN) The key for the second ptr.
See also:
gm_hash_compare_longs gm_hash_compare_strings gm_hash_compare_ints
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT unsigned long gm_hash_hash_ptr void *    key
 

gm_hash_hash_ptr() is the function used to hash keys.

Return values:
long 
Parameters:
key  (IN)
See also:
gm_hash_compare_ptr gm_hash_hash_int gm_hash_hash_long gm_hash_hash_string
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)


Generated on Mon Nov 3 15:39:26 2003 for GM by doxygen1.2.15