NAME

cp_heap_create, cp_heap_create_by_option cp_heap_destroy - create / destroy a heap

SYNOPSIS

#include <cprops/heap.h>

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.

SEE ALSO

cp_hashtable(3), cp_heap_push(3), cp_heap_pop(3)