cp_hashlist

Section: libcprops - cp_hashlist (3)
Updated: OCTOBER 2005
Index Return to Main Contents

NAME

cp_hashlist_create, cp_hashlist_create_by_mode, cp_hashlist_create_by_option - hashlist constructor functions

SYNOPSIS

cp_hashlist *cp_hashlist_create(long initial_size,
cp_hashfunction hash_fn,
cp_compare_fn compare_fn);

cp_hashlist *cp_hashlist_create_by_mode(int mode,
                                         int initial_size,
                                         cp_hashfunction hash_fn,
                                         cp_compare_fn compare_fn);

cp_hashlist *
      cp_hashlist_create_by_option(int mode,
                                   long initial_size,
                                   cp_hashfunction hash_fn,
                                   cp_compare_fn compare_fn,
                                   cp_copy_fn copy_key,
                                   cp_destructor_fn free_key);
                                   cp_copy_fn copy_value
                                   cp_destructor_fn free_value);

DESCRIPTION

cp_hashlist_create creates a hashlist using initial_size as an estimate for the required list size, hash_fn to index items by key, and the comparison function compare_fn. The hash function should follow the following prototype

long hash_fn(void *key);

and should return a number based on the key so that different keys yield different numbers to the extent possible. However since different keys may yield the same hash code a comparison function defined as

int hash_compare(void *a, void *b);

is needed to ultimately identify the requested key upon retrieval. The comparison function should return 0 for matching items, non-zero otherwise. See cp_hashtable_create(3) for more on hash and comparison functions and cp_hashtable(3) for a list of predefined hash functions for primitives and null terminated strings.

Lists created with the default mode (0) synchronize table operations (item insertion, iteration, retrieval and removal, internal table resizing and deleting) and perform no memory management. Different behavior can also be specified by calling cp_hashlist_create_by_mode and specifying a mode value. See cp_hashlist_set_mode(3) for a list of mode bits and their effect on list behavior.

In addition to list mode, cp_hashlist_create_by_option allows specifying copy and finalization functions for keys and values respectively. Copy functions are called on insertion if not NULL and COLLECTION_MODE_COPY is set and finalization functions are called on removal if not NULL and COLLECTION_MODE_DEEP is set. Copy functions should be defined as

void *copy_fn(void *);

and should return a pointer to a copy of the key or value passed. Destructor functions should be defined as

void *destructor_fn(void *);

and should release the memory associated with the key or value passed.

All mode bits can be set or reset after creation time by calling cp_hashlist_set_mode and cp_hashlist_unset_mode. Note that lists constructed with COLLECTION_MODE_NOSYNC set do not initialize the synchronization features, and subsequent attempts to perform thread safe operations may behave unpredictably. Hashlists that may be accessed by multiple threads at any point should not be initialized with COLLECTION_MODE_NOSYNC.

RETURN VALUE

all constructor functions return a pointer to a newly allocated hashlist instance on success, or NULL on failure.

ERRORS

ENOMEM an internal memory allocation failed.

EINVAL a negative initial_size was requested.

This document was created by man2html, using the manual pages.
Time: 18:37:21 GMT, December 27, 2005