cp_list
Section: libcprops overview (3)
Updated: OCTOBER 2005
Index
Return to Main Contents
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)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- CONSTRUCTOR / DESTRUCTOR FUNCTIONS
-
- ADDING ITEMS
-
- RETREIVING ITEMS
-
- SYNCHRONIZATION
-
- OTHER
-
- RETURN VALUE
-
- ERRORS
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 12:01:45 GMT, May 23, 2006
|
|