390 lines
10 KiB
C
390 lines
10 KiB
C
/* ipcom_hash.h - API of IPCOM Hash Table */
|
|
|
|
/*
|
|
******************************************************************************
|
|
* INTERPEAK API HEADER FILE
|
|
*
|
|
* Document no: @(#) $Name: VXWORKS_ITER40_2019102207 $ $RCSfile: ipcom_hash.h,v $ $Revision: 1.19 $
|
|
* $Source: /home/interpeak/CVSRoot/ipcom/include/ipcom_hash.h,v $
|
|
* $Author: kenneth $ $Date: 2008-12-10 20:44:19 $
|
|
* $State: Exp $ $Locker: $
|
|
*
|
|
* INTERPEAK_COPYRIGHT_STRING
|
|
* Design and implementation by Kenneth Jonsson <kenneth@interpeak.se>
|
|
******************************************************************************
|
|
*/
|
|
#ifndef IPCOM_HASH_H
|
|
#define IPCOM_HASH_H
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 1 DESCRIPTION
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*
|
|
DESCRIPTION
|
|
This library contains the API for IPCOM Hash Table
|
|
*/
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 2 CONFIGURATION
|
|
****************************************************************************
|
|
*/
|
|
|
|
#include "ipcom_config.h"
|
|
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 3 INCLUDE FILES
|
|
****************************************************************************
|
|
*/
|
|
|
|
#include <ipcom_type.h>
|
|
#include <ipcom_cstyle.h>
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 4 DEFINES
|
|
****************************************************************************
|
|
*/
|
|
|
|
#if !defined(IPCOM_KERNEL) && defined(IPCOM_USRLIB)
|
|
#define ipcom_hash_new ipcom_hash_new_usr
|
|
#define ipcom_hash_delete ipcom_hash_delete_usr
|
|
#define ipcom_hash_add ipcom_hash_add_usr
|
|
#define ipcom_hash_remove ipcom_hash_remove_usr
|
|
#define ipcom_hash_get ipcom_hash_get_usr
|
|
#define ipcom_hash_for_each ipcom_hash_for_each_usr
|
|
#define ipcom_hash_update ipcom_hash_update_usr
|
|
#endif
|
|
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 5 TYPES
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*
|
|
*===========================================================================
|
|
* Ipcom_hash_obj_func
|
|
*===========================================================================
|
|
* Description: Computes a hash value for the (used defined) object.
|
|
* Parameters: obj - The object to calculate the hashvalue for.
|
|
* Returns: The hash value
|
|
*
|
|
*/
|
|
typedef unsigned (*Ipcom_hash_obj_func)(const void *obj);
|
|
|
|
/*
|
|
*===========================================================================
|
|
* Ipcom_hash_key_func
|
|
*===========================================================================
|
|
* Description: Computes a hash value for the (used defined) search key.
|
|
* Parameters: key - The key to calculate the hashvalue for.
|
|
* Returns: The hash value
|
|
*
|
|
*/
|
|
typedef unsigned (*Ipcom_hash_key_func)(const void *key);
|
|
|
|
/*
|
|
*===========================================================================
|
|
* Ipcom_hash_cmp_func
|
|
*===========================================================================
|
|
* Description: Compares the (user defined) object with the (used defined)
|
|
* search key. This must always be true:
|
|
* if Ipcom_hash_cmp_func(obj, key) == IP_TRUE
|
|
* then Ipcom_hash_obj_func(obj) == Ipcom_hash_key_func(key)
|
|
* Parameters: obj - An object that can/is stored in the hash table.
|
|
* key - The key used when making lookups in the hash table.
|
|
* Returns: IP_TRUE if the key matches the object, IP_FALSE otherwise.
|
|
*
|
|
*/
|
|
typedef Ip_bool (*Ipcom_hash_cmp_func)(const void *obj, const void *key);
|
|
|
|
/*
|
|
*===========================================================================
|
|
* Ipcom_hash_foreach_cb_func
|
|
*===========================================================================
|
|
* Description: Callback function that is called for each element in the hash
|
|
* table when using ipcom_hash_for_each().
|
|
* Parameters: obj - A object in the hash table.
|
|
* data - User defined data passed to ipcom_hash_for_each().
|
|
* Returns:
|
|
*
|
|
*/
|
|
typedef void (*Ipcom_hash_foreach_cb_func)(void *obj, void *data);
|
|
|
|
/*
|
|
*===========================================================================
|
|
* Ipcom_hash
|
|
*===========================================================================
|
|
* List head and entry structure.
|
|
*/
|
|
typedef struct Ipcom_hash_struct
|
|
{
|
|
/* Function that creates a hash value from an object */
|
|
Ipcom_hash_obj_func obj_hash_func;
|
|
|
|
/* Pointer to a function that creates a hash value from a search key */
|
|
Ipcom_hash_key_func key_hash_func;
|
|
|
|
/* Function that compares an objects and a search key and return the result */
|
|
Ipcom_hash_cmp_func obj_key_cmp;
|
|
|
|
unsigned elem; /* The number of elements currently in the table */
|
|
unsigned size; /* The size of the hash table */
|
|
void **table; /* The hash table */
|
|
}
|
|
Ipcom_hash;
|
|
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 6 FUNCTIONS
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_new - create a new hash table
|
|
*
|
|
* This routine creates a new hash table.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <obj_hash>
|
|
* A function that creates a hash value for object <obj>.
|
|
* \i <key_hash>
|
|
* A function that creates a hash value for search key <key>.
|
|
* \i <cmp>
|
|
* A function that will evaluate to 'IP_TRUE' if <key> is the search key that
|
|
* matches <obj>.
|
|
* \ie
|
|
*
|
|
* RETURNS: Pointer to the new hash table or 'IP_NULL' if not enough memory could
|
|
* be allocated.
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC Ipcom_hash *ipcom_hash_new
|
|
(
|
|
Ipcom_hash_obj_func obj_hash_func,
|
|
Ipcom_hash_key_func key_hash_func,
|
|
Ipcom_hash_cmp_func obj_key_cmp
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_delete - free the hash table
|
|
*
|
|
* This routine frees the hash table. Not that the object stored in the hash
|
|
* table is not freed.
|
|
*
|
|
* Parameter:
|
|
* \is
|
|
* \i <head>
|
|
* The hash table head (returned from ipcom_hash_new()).
|
|
* \ie
|
|
*
|
|
* RETURNS: \&N/A.
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC void ipcom_hash_delete
|
|
(
|
|
Ipcom_hash *head
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_add - add an object to the hash table
|
|
*
|
|
* This routine adds an object to the hash table.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <hash>
|
|
* The hash table the object is added to.
|
|
* \i <obj>
|
|
* The object to add.
|
|
* \ie
|
|
*
|
|
* RETURNS: 'IPCOM_SUCCESS', or one of the following errors:
|
|
* \is
|
|
* \i 'IPCOM_ERR_DUPLICATE'
|
|
* If the object was already in the hash table.
|
|
* \i 'IPCOM_ERR_NO_MEMORY'
|
|
* If the hash table failed to increase in size. The hash table will grow when it
|
|
* gets too densely populated.
|
|
* \ie
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC Ip_err ipcom_hash_add
|
|
(
|
|
Ipcom_hash *head,
|
|
void *obj
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_remove - remove an object from the hash table
|
|
*
|
|
* This routine removes an object from the hash table. Note that the resources
|
|
* held by the object are not freed.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <head>
|
|
* The hash table the object will be removed from.
|
|
* \i <obj>
|
|
* The object to remove.
|
|
* \ie
|
|
*
|
|
* RETURNS:
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC Ip_err ipcom_hash_remove
|
|
(
|
|
Ipcom_hash *head,
|
|
void *obj
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_get - return the matching object
|
|
*
|
|
* This routine returns the object, if there is one, that matches the <key>
|
|
* parameter.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <head>
|
|
* The hash table to search.
|
|
* \i <key>
|
|
* The search key to use when looking for the object.
|
|
* \ie
|
|
*
|
|
* RETURNS: A pointer to the object, or 'IP_NULL' if no object exists that
|
|
* matches <key>.
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_FASTTEXT IP_PUBLIC void *ipcom_hash_get
|
|
(
|
|
Ipcom_hash *head,
|
|
const void *key
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_for_each - call cb_func
|
|
*
|
|
* This routine calls cb_func() for each object in the hash table. Note that
|
|
* the order of the objects must be considered completely random.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <head>
|
|
* The hash table to traverse.
|
|
* \i <cb_func>
|
|
* The function to call for each object.
|
|
* \i <data>
|
|
* User define data that will passed as second argument to cb_func().
|
|
* \ie
|
|
*
|
|
* RETURNS:
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC void ipcom_hash_for_each
|
|
(
|
|
Ipcom_hash *head,
|
|
Ipcom_hash_foreach_cb_func cb_func,
|
|
void *data
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
*
|
|
* ipcom_hash_update - create a hash value from the key
|
|
*
|
|
* This routine creates a hash value from a key given in the <key> parameter. The
|
|
* function can be called repeatedly to include any number of keys in the final
|
|
* hash value.
|
|
*
|
|
* Parameters:
|
|
* \is
|
|
* \i <key>
|
|
* The key to hash.
|
|
* \i <key_len>
|
|
* The length of the key, in octets.
|
|
* \i <initval>
|
|
* The previous hash value, or any value, if this is the first time the function
|
|
* is called. The value used in the first call is constant for the lifetime of
|
|
* the hash table.
|
|
* \ie
|
|
*
|
|
* EXAMPLE
|
|
* \cs
|
|
* struct My_struct
|
|
* {
|
|
* int a;
|
|
*
/@ Data that we do not want to include
|
|
* in the hash value @/
|
|
* int b;
|
|
* };
|
|
*
|
|
* /@ Example implementation for the obj_hash() function @/
|
|
* unsigned obj_hash(struct My_struct *m)
|
|
* {
|
|
* unsigned h;
|
|
* /@ The initval can be any value in the first call @/
|
|
* h = ipcom_hash_update(&m->a, sizeof(m->a), 0x2653145);
|
|
* /@ The initval must be the previous hash value in
|
|
* consecutive calls @/
|
|
* h = ipcom_hash_update(&m->b, sizeof(m->b), h);
|
|
* return h;
|
|
* }
|
|
* \ce
|
|
*
|
|
* RETURNS: The hash value for the key
|
|
*
|
|
* ERRNO:
|
|
*/
|
|
IP_PUBLIC unsigned ipcom_hash_update
|
|
(
|
|
const void *key,
|
|
int key_len,
|
|
unsigned initval
|
|
);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
|
|
|
|
/*
|
|
****************************************************************************
|
|
* END OF FILE
|
|
****************************************************************************
|
|
*/
|