PblIterator* pblPriorityQueueIterator

( PblPriorityQueue* queue )

Returns an iterator over the elements in the queue.

Documentation

Returns an iterator over the elements in the queue.

The iterator starts the iteration at the element with the highest priority.

Note: The memory allocated by this method for the iterator returned needs to be released by calling pblIteratorFree() once the iterator is no longer needed.

The pointers returned by the pblIteratorNext() or pblIteratorPrevious() functions of the iterator are of type PblPriorityQueueEntry allowing to access priority and element.

Modifying the priority queue via the Iterator's own remove or add methods does not maintain the heap property of the priority queue. In this case the heap property has to be restored by a call to pblPriorityQueueConstruct().

The iterators returned by the this method are fail-fast: if the queue is structurally modified at any time after the iterator is created, in any way except through the Iterator's own remove or add methods, the iterator will return a PBL_ERROR_CONCURRENT_MODIFICATION error.

Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

This method has a time complexity of O(1).

Parameters:

queue - The queue to use

Returns:

void * retptr != NULL: The iterator.
void * retptr == NULL: An error, see pbl_errno:
PBL_ERROR_OUT_OF_MEMORY - Out of memory.

Alphabetic index