NAME

cp_priority_list - a priority queue implementation

SYNOPSIS

#include <cprops/priority_list.h>

cp_priority_list *cp_priority_list_create(int immediate, int normal, int *weights);
cp_priority_list * cp_priority_list_create_by_option(int immediate, int normal, int *weights, cp_compare_fn compare_fn, cp_copy_fn copy_fn, cp_destructor_fn destructor_fn, int mode);
void cp_priority_list_destroy(cp_priority_list *list);
void cp_priority_list_destroy_by_option(cp_priority_list *list, int option);

void *cp_priority_list_insert(cp_priority_list *list, void *item, int priority);
void *cp_priority_list_insert_by_option(cp_priority_list *list, void *item, int priority, int mode);

void *cp_priority_list_get_next(cp_priority_list *list);
void *cp_priority_list_get_next_by_option(cp_priority_list *list, int mode);

int cp_priority_list_lock(cp_priority_list *list, int lock_mode);
int cp_priority_list_rdlock(cp_priority_list *list);
int cp_priority_list_wrlock(cp_priority_list *list);
int cp_priority_list_unlock(cp_priority_list *list);

long cp_priority_list_item_count(cp_priority_list *list);
int cp_priority_list_is_empty(cp_priority_list *list);

DESCRIPTION

cp_priority_list is a priority queue implementation featuring an optional ``immediate'' priority queue and any number of ``normal'' weighted queues. Internally each of these is implemented as a separate linked list. Normal priority queues are assigned weights at instantiation. These weights are the number of items that are extracted from a queue before switching to the next queue, to the extent that the queues are full and there are no immediate priority items. E.g. defining two normal priority queues with weights 5 and 3, extraction methods will attempt to extract 5 items from the index 1 queue, then 3 item from the index 2 queue and so forth. Index 0 is reserved for the immediate priority queue.
Items pushed with the same priority index are extracted in order (FIFO).

CONSTRUCTOR / DESTRUCTOR FUNCTIONS

cp_priority_list_create creates a priority list with normal normal priority queues with weights as defined by the weights array. If immediate is non-zero, the list will be created with an immediate queue.
The default mode for priority lists is COLLECTION_MODE_MULTIPLE_VALUES and item insertion and removal are synchronized. Different behavior can be requested with cp_priority_list_create_by_option which allows specifying a different mode, an item comparison function compare_fn which is used if not setting the COLLECTION_MODE_MULTIPLE_VALUES bit, a copy function copy_fn which is used if setting the COLLECTION_MODE_COPY bit and an item destructor function destructor_fn which is invoked upon item removal if the COLLECTION_MODE_DEEP mode bit is set. For additional disscussion of mode bits see cp_list(3).

ADDING ITEMS

cp_priority_list_insert adds an item in the list's default mode to the queue with the index priority. The index 0 denotes the immediate priority queue. cp_priority_list_insert_by_option allows specifying the operation mode with the mode parameter. Note that unless the COLLECTION_MODE_MULTIPLE_VALUES bit is set all lists are scanned to ensure that the item being inserted is not already present.

RETREIVING ITEMS

cp_priority_list_get_next returns the next item from the list by priority using the list's default mode. The next item is determined as described above. cp_priority_list_get_next_by_option uses the mode specified by the mode parameter. In particular setting the COLLECTION_MODE_DEEP bit will have the effect of calling free(3) on the retreived item.
Both functions return NULL if the list is empty.

SYNCHRONIZATION

call cp_priority_list_lock with the mode parameter set to COLLECTION_LOCK_READ to obtain a read-lock, or to COLLECTION_LOCK_WRITE to obtain a write-lock on a list. The macros cp_priority_list_rdlock and cp_priority_list_wrlock may also be used to the same effect. Calls to locking functions must be coupled with a call to cp_priority_list_unlock to release the lock. As for other collection objects, explicit locking is only required when several operations must complete before allowing other threads access to the list. Otherwise single list operations are synchronized unless COLLECTION_MODE_NOSYNC is specified.

Priority lists are synchronized by default. Create the list with the COLLECTION_MODE_NOSYNC mode bit set to override this.

OTHER

cp_priority_list_item_count returns the number of items currently in the list.
cp_priority_list_is_empty returns non-zero is the list is empty, 0 otherwise.

RETURN VALUE

constructor functions return a pointer to a newly allocated cp_priority_list or NULL on failure.
insertion and retrieval and removal functions return a pointer to the added item or NULL if the operation failed.
synchronization functions return 0 on success, non-zero on error.

ERRORS

EINVAL

attempting to insert an item with an undefined priority index.

ENOMEM

an internal memory allocation failed.

SEE ALSO

cp_list(3)