PQ(3PT)

NAME
pq_create, pq_destroy, pq_head, pq_extract_head, pq_insert, pq_delete - functions that manage priority queues

SYNOPSIS

#include "pq.h"

pq_h pq_create( func, flags, errnop )
int (*func)() ;
int flags ;
int *errnop ;

void pq_destroy( pq )
pq_h pq ;

pq_obj pq_head( pq )
pq_h pq ;

pq_obj pq_extract_head( pq )
pq_h pq ;

int pq_insert( pq, object )
pq_h pq ;
pq_obj object ;

int pq_delete( pq, object )
pq_h pq ;
pq_obj object ;

DESCRIPTION

This library handles priority queues that contain objects. Objects are of type pq_obj which is a pointer type. The object at the head of a priority queue is the best object. The user defines the ordering by providing a function that compares objects when the priority queue is created.

pq_create() creates a priority queue and returns a handle to be used for operations on that queue. func is a pointer to a function that takes 2 objects as arguments and returns 1 if the first object is better than the second and 0 otherwise. The only possible value for the flags argument is PQ_RETURN_ERROR which if used will cause queue operations applied on the specific priority queue to return an error status if they fail (the default is to terminate the program with an appropriate error message). The value PQ_NOFLAGS can be used to specify no flags. The errnop argument is a pointer to an integer where an error code will be stored if an operation fails (and PQ_RETURN_ERROR is used). If no pointer is specified, error codes are placed in the global variable pq_error.

pq_destroy() is used to destroy a priority queue.

pq_head() returns the object at the head of the priority queue.

pq_extract_head() extracts and returns the object at the head of the priority queue.

pq_insert() inserts the given object in the priority queue.

pq_delete() deletes the given object from the priority queue.

RETURN VALUES

In the following, values for pq_errno will be stored in the user-specified variable if one was provided.

pq_create() returns a priority queue handle if successful, or NULL if it fails. Possible pq_errno values:

    PQ_ENOFUNC
        The object comparison function is missing.

    PQ_ENOMEM
        The program ran out of memory.

pq_insert() returns PQ_OK if successful and PQ_ERR if it fails. Possible pq_errno values:

    PQ_ENULLOBJECT
        The object value is NULL.

    PQ_ENOMEM
        The program ran out of memory.

pq_head() returns the object at the head of the queue or NULL if the queue is empty.

pq_extract_head() returns the object at the head of the queue or NULL if the queue is empty.

pq_delete() returns PQ_OK if successful and PQ_ERR if it fails. Possible pq_errno values:

    PQ_ENULLOBJECT
        The object value is NULL.

    PQ_ENOTFOUND
        The object is not in the queue.