cp_heap

Section: libcprops - cp_heap (3)
Updated: JULY 2006
Index Return to Main Contents

NAME

cp_heap_create, cp_heap_create_by_option cp_heap_destroy - create / destroy a heap

SYNOPSIS

cp_heap *cp_heap_create(cp_compare_fn cmp);
cp_heap *
      cp_heap_create_by_option(int mode,
                               int size_hint,
                               cp_compare_fn compare_fn,
                               cp_copy copy,
                               cp_destructor_fn dtr);

void cp_heap_destroy(cp_heap *heap);

DESCRIPTION

cp_heap_create creates an empty synchronized heap using the given compare function. The compare function should implement ``strcmp semantics'' and conform to the following prototype:

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

The return value should be

> 0  if A > B

= 0  if A == B

< 0  if A < B
where A and B are the items pointed at by pointers a and b respectively. The functions cp_hash_compare_* defined in <cprops/hashtable.h> may be used for cp_heap as well.

cp_heap_create_by_option allow specifying an initial mode, a size hint and item copy and destructor functions. The constructed heap is initialized with sufficient storage to accomodate at least size_hint items. If the heap mode has the COLLECTION_MODE_NOSYNC bit set, heap operations do not perform locking. If the COLLECTION_MODE_COPY bit is set, subsequent cp_heap_push (3) calls will insert the copy obtained using the copy function to the heap. If the COLLETION_MODE_DEEP bit is set, cp_heap_pop (3) and cp_heap_destroy (3) invoke the dtr function on the items being removed from the heap.

cp_heap_destroy releases the memory associated with the given heap.

RETURN VALUE

cp_heap_create and cp_heap_create_by_option return a newly allocated heap structure on success or NULL on failure.