Provided by: libglobus-common-doc_14.10-2_all 
NAME
Priority Queue -
Data Structures
struct globus_priority_q_s
Typedefs
typedef int(* globus_priority_q_cmp_func_t )(void *priority_1, void *priority_2)
typedef struct globus_priority_q_s globus_priority_q_t
Functions
int globus_priority_q_init (globus_priority_q_t *priority_q, globus_priority_q_cmp_func_t
cmp_func)
int globus_priority_q_destroy (globus_priority_q_t *priority_q)
globus_bool_t globus_priority_q_empty (globus_priority_q_t *priority_q)
int globus_priority_q_size (globus_priority_q_t *priority_q)
int globus_priority_q_enqueue (globus_priority_q_t *priority_q, void *datum, void
*priority)
void * globus_priority_q_dequeue (globus_priority_q_t *priority_q)
void * globus_priority_q_first (globus_priority_q_t *priority_q)
void * globus_priority_q_first_priority (globus_priority_q_t *priority_q)
void * globus_priority_q_remove (globus_priority_q_t *priority_q, void *datum)
void * globus_priority_q_modify (globus_priority_q_t *priority_q, void *datum, void
*new_priority)
Detailed Description
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
int globus_priority_q_init (globus_priority_q_t *priority_q,
globus_priority_q_cmp_func_tcmp_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
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_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.
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_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.
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.
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
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.
Author
Generated automatically by Doxygen for globus common from the source code.