cnet's support functions

NAME
Hashtable support functions.

SYNOPSIS
#include <cnet.h>
#include <cnetsupport.h>

typedef void *    HASHTABLE;
extern  HASHTABLE *hashtable_new(int nbuckets);
extern  void      hashtable_free(HASHTABLE ht);
extern  void      hashtable_add(HASHTABLE ht, char *name, void *item, size_t len);
extern  void      *hashtable_remove(HASHTABLE ht, char *name, size_t *len);
extern  void      *hashtable_find(HASHTABLE ht, char *name, size_t *len);
extern  int       hashtable_nitems(HASHTABLE ht);

DESCRIPTION
It is a common requirement of network protocols to manage items, such as the elements of a routing table, with a hashtable. This set of functions supports the maintenance of hashtables of arbitrary data. A cnet node may have an unlimited number of such hashtables.

A new hashtable is firstly allocated by calling hashtable_new, and should eventually be deallocated with a call to hashtable_free. The opaque value returned by hashtable_new should be passed to all other functions, to identify which hashtable is being used. The required number of buckets is passed to hashtable_new - indicating 0 buckets requests the default.

Items, of any type, may be added to a hashtable with hashtable_add. The functions do not know what they are managing, and so you must also provide the length, in bytes, of each added item. A copy is made of all items added to a hashtable. The number of items in a hashtable may be determined at any time by calling hashtable_nitems.

Finding an item in a hashtable leaves the item in the hashtable, and returns a pointer to the found item, and informs you of its length. hashtable_remove deallocates the space occopied by a requested item. hashtable_free deallocates the space occopied by all items and the hashtable itself.

EXAMPLE
A typical use of these functions is:

    HASHTABLE   myht   = hashtable_new(0);
    TYPE        mydata, *myptr;
    size_t      len;

    hashtable_add(myht, "apple",  &mydata, sizeof(mydata));
    hashtable_add(myht, "banana", &mydata, sizeof(mydata));
        ....
    myptr = hashtable_find(myht, "orange", &len);
    if(myptr) {
        ....
    }
    hashtable_free(myht);


 cnet v3.3.4, written by Chris.McDonald@uwa.edu.au
 Last modified: Tue Mar 1 7:43AM 2016