NAME

       globus_priority_q - Priority Queue

        - Priority Queue.

SYNOPSIS

   Data Structures
       struct globus_priority_q_s
           Priority Queue Structure.

   Typedefs
       typedef int(* globus_priority_q_cmp_func_t) (void *priority_1, void *priority_2)
           Priority Comparison Predicate.
       typedef struct globus_priority_q_s globus_priority_q_t
           Priority Queue Structure.

   Functions
       int globus_priority_q_init (globus_priority_q_t *priority_q, globus_priority_q_cmp_func_t cmp_func)
           Initialize a priority queue.
       int globus_priority_q_destroy (globus_priority_q_t *priority_q)
           Destroy a Priority Queue.
       globus_bool_t globus_priority_q_empty (globus_priority_q_t *priority_q)
           Priority Queue Empty Predicate.
       int globus_priority_q_size (globus_priority_q_t *priority_q)
           Priority Queue Size.
       int globus_priority_q_enqueue (globus_priority_q_t *priority_q, void *datum, void *priority)
           Add a Datum to a Priority Queue.
       void * globus_priority_q_dequeue (globus_priority_q_t *priority_q)
           Remove a Datum From A Priority Queue.
       void * globus_priority_q_first (globus_priority_q_t *priority_q)
           Get the Highest-Priority Datum From a Priority Queue.
       void * globus_priority_q_first_priority (globus_priority_q_t *priority_q)
           Get the Highest Priority in Priority Queue.
       void * globus_priority_q_remove (globus_priority_q_t *priority_q, void *datum)
           Remove an Arbitrary Datum from a Priority Queue.
       void * globus_priority_q_modify (globus_priority_q_t *priority_q, void *datum, void *new_priority)
           Modify the Priority of Datum.

Detailed Description

       Priority Queue.

       This module defines a priority queue for globus. It is implemented using a binary heap (minheap) and does
       NOT have a fifo fallback for like priorities. If you need fifo fallback, you should use a compound
       priority with the primary priority being the 'real' priority and the secondary being a serial number.

       To use this priority queue type, define a comparison function of type globus_priority_q_cmp_func_t and
       pass that to globus_priority_q_init().

       To add and remove items in priority order, use globus_priority_q_enqueue() and
       globus_priority_q_dequeue() respectively.

       To remove a datum ignoring its priority, use globus_priority_q_remove().

       To inspect the first element and its priority, use globus_priority_q_first() and
       globus_priority_q_first_priority() respectively.

       To determine whether a queue is empty or the number of data in it, use globus_priority_q_empty() and
       globus_priority_q_size().

       To modify the priority of a datum already in the queue, use globus_priority_q_modify().

       When finished with the queue, use globus_priority_q_destroy() to free data associated with the priority
       queue.

Typedef Documentation

   typedef int(* globus_priority_q_cmp_func_t) (void *priority_1, void *priority_2)
       Priority Comparison Predicate. This type is used to implement comparison of two priorities for inserting
       items into the priority queue. A function of this type is passed to globus_priority_q_init() to determine
       how priorities are computed in a newly created priority queue.

       Parameters
           priority_1 First priority to compare
           priority_2 Second priority to compare

       Return values
           > 0 The priority of priority_1 is less than that of priority_2.
           < 0 The priority of priority_1 is greater than that of priority_2.
           = 0 The priorities of priority_1 and priority_2 are the same.

   typedef struct globus_priority_q_s globus_priority_q_t
       Priority Queue Structure. A pointer to a structure of this type is passed to all functions in the
       Priority Queue  module. It is not intended to be inspected or modified outside of this API.

Function Documentation

   void * globus_priority_q_dequeue (globus_priority_q_t * priority_q)
       Remove a Datum From A Priority Queue. The globus_priority_q_dequeue() function removes the highest-
       priority datum from the given priority queue and returns it. If the priority_q pointer is NULL or the
       priority queue is empty, this function returns NULL.

       Parameters
           priority_q Pointer to the priority queue to remove from.

       Returns
           This function returns the highest-priority datum from the priority queue.

   int globus_priority_q_destroy (globus_priority_q_t * priority_q)
       Destroy a Priority Queue. The globus_priority_q_destroy() function destroys the contents of a priority
       queue. After this function returns, the structure pointed to by priority_q is invalid and must not be
       passed to any functions in the Priority Queue  module other globus_priority_q_init().

       Note that this function does not call any destructors for the data inserted into the priority queue, so
       the caller must be sure to either have other references to those data or free them before calling this
       function.

       Parameters
           priority_q Pointer to the priority_q to destroy.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_FAILURE Failure

   globus_bool_t globus_priority_q_empty (globus_priority_q_t * priority_q)
       Priority Queue Empty Predicate. The globus_priority_q_empty() function checks the given priority queue to
       determine if it is empty. It is considered empty if it has been initialized via globus_priority_q_init()
       and there are no items which have been inserted via globus_priority_q_enqueue() which have not been
       removed by calling globus_priority_q_remove() or globus_priority_q_dequeue(). If it is empty, this
       function returns GLOBUS_TRUE; otherwise it returns GLOBUS_FALSE.

       Parameters
           priority_q Pointer to the priority queue to check

       Return values
           GLOBUS_TRUE The priority queue is empty
           GLOBUS_FALSE The priority queue is not empty, or the priority queue is invalid

   int globus_priority_q_enqueue (globus_priority_q_t * priority_q, void * datum, void * priority)
       Add a Datum to a Priority Queue. The globus_priority_q_enqueue() function inserts a datum into the
       priority queue based on its priority. When an item is inserted, the pointers to both the datum and the
       priority are copied into the priority_q data structure, so neither may be freed until the datum is
       removed from the priority queue, or undefined behavior may occur.

       Note that there is no fifo fallback for priorities, so the order of two items with equivalent priorities
       is not specified relative to each other. To enable fifo fallback, use a compound priority that includes a
       priority level and a sequence number as the value pointed to by the priority parameter and pass a
       suitable comparison function to initialize the priority queue.

       Parameters
           priority_q Pointer to the priority queue to insert datum into
           datum The datum to insert into the queue
           priority The priority of the datum

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_FAILURE Failure

   void * globus_priority_q_first (globus_priority_q_t * priority_q)
       Get the Highest-Priority Datum From a Priority Queue. The globus_priority_q_first() function returns the
       highest-priority datum from the priority queue pointed to by priority_q. The datum is not removed from
       the queue; to do that, use globus_priority_q_dequeue() instead. If the priority_q pointer is NULL or the
       queue is empty, this function returns NULL. The priority queue retains a reference to the returned datum,
       so the pointer value returned must not freed until the datum is removed from the queue.

       Parameters
           priority_q Pointer to the priority queue to inspect

       Returns
           This function returns the highest-priority datum from the priority queue.

   void * globus_priority_q_first_priority (globus_priority_q_t * priority_q)
       Get the Highest Priority in Priority Queue. The globus_priority_q_first_priority() function returns the
       value of highest priority in the priority queue (not the datum associated with that priority). If the
       priority_q pointer is NULL or empty, this function returns NULL. The priority queue retains a reference
       to the returned priority, so the pointer value returned must not be freed until the datum associated with
       it is removed from the queue.

       Parameters
           priority_q Pointer to the priority queue to inspect

       Returns
           This function returns the highest priority value in the priority queue.

   int globus_priority_q_init (globus_priority_q_t * priority_q, globus_priority_q_cmp_func_t cmp_func)
       Initialize a priority queue. The globus_priority_q_init() function initializes a globus_priority_q_t
       structure for use with the other functions in the Priority Queue  module. If this function returns
       GLOBUS_SUCCESS, the caller is responsible for deallocating the members of this structure when it is no
       longer needed by passing it to globus_priority_q_destroy().

       Parameters
           priority_q Pointer to the priority queue structure to initialize.
           cmp_func Pointer to a function which computes the relative relationship between two priorities. See
           the documentation of globus_priority_q_cmp_func_t for details on how to implement that function.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_FAILURE Failure

   void * globus_priority_q_modify (globus_priority_q_t * priority_q, void * datum, void * new_priority)
       Modify the Priority of Datum. The globus_priority_q_modify() function modifies the priority of the
       highest-priority instance of datum in the priority queue so that it new_priority. The old priority of the
       datum is returned. If the priority_q is NULL or the datum is not present, this function returns NULL.

       Parameters
           priority_q Pointer to the priority queue to modify
           datum Pointer to the datum whose priority is being modified
           new_priority Pointer to the new priority

       Returns
           This function returns the old priority of datum.

   void * globus_priority_q_remove (globus_priority_q_t * priority_q, void * datum)
       Remove an Arbitrary Datum from a Priority Queue. The globus_priority_q_remove() function removes the
       highest-priority instance of the specified datum from the priority queue and returns the datum if it is
       found. If the priority_q is NULL or the datum is not found, this function returns NULL.

       Parameters
           priority_q Pointer to the priority queue to modify
           datum Pointer to the datum to search for.

       Returns
           This function returns datum if it was present in the priority queue

   int globus_priority_q_size (globus_priority_q_t * priority_q)
       Priority Queue Size. The globus_priority_q_size() function returns the size of the priority queue, that
       is, the number of elements that are currently enqueued in it. The special value GLOBUS_FAILURE is
       returned if a null pointer is passed to this function.

       Parameters
           priority_q Pointer to the priority queue to check

       Returns
           This function returns the number of elements in the queue, or GLOBUS_FAILURE if the priority_q
           pointer is invalid.

Author

       Generated automatically by Doxygen for globus_common from the source code.

globus_common                                     Version 18.14                             globus_priority_q(3)