6.3.9 Queue functions

Because queues are a widely applicable construct, the run-time library provides support for queues of arbitrary datatypes. In the current implementation, these can more precisely be termed “dynamically growing lists” than “queues”. However, they may be extended in a future version of the library to support more queue-like functionality.

Function: NCPTL_QUEUE * ncptl_queue_init (ncptl_int eltbytes)

ncptl_queue_init() creates and initializes a dynamically growing queue in which each element occupies eltbytes bytes of memory.

Function: void * ncptl_queue_allocate (NCPTL_QUEUE *queue)

Allocate a new data element at the end of queue queue. The queue passed to ncptl_queue_allocate() must be one returned by ncptl_queue_init(). ncptl_queue_allocate() returns a pointer to the data element allocated.

Function: void * ncptl_queue_push (NCPTL_QUEUE *queue, void *element)

Push (via a memory copy) the element pointed to by element onto the end of queue queue and return a pointer to the copy in the queue. The queue passed to ncptl_queue_allocate() must be one returned by ncptl_queue_init(). ( ncptl_queue_push() is actually implemented in terms of ncptl_queue_allocate() .)

Function: void ncptl_queue_push_all (NCPTL_QUEUE *target_queue, NCPTL_QUEUE *source_queue)

Push (via a memory copy) all of the elements in source_queue onto the end of target_queue. A fatal error will occur if the two queues were not initialized with the same eltbytes argument to ncptl_queue_init(). ncptl_queue_push_all() does not modify source_queue.

Function: void * ncptl_queue_pop (NCPTL_QUEUE *queue)

Pop a pointer to the element at the head of queue queue. If queue is empty, return NULL. The pointer returned by ncptl_queue_pop() is guaranteed to be valid until the next invocation of ncptl_queue_empty().

Function: void * ncptl_queue_pop_tail (NCPTL_QUEUE *queue)

Pop a pointer to the element at the tail of queue queue. If queue is empty, return NULL. In essence, this lets the caller treat the queue as a stack. The pointer returned by ncptl_queue_pop_tail() is guaranteed to be valid until the next invocation of ncptl_queue_empty(), ncptl_queue_allocate() or ncptl_queue_push().

Function: void * ncptl_queue_contents (NCPTL_QUEUE *queue, int copyelts)

Return queue queue as an array of elements. If ncptl_queue_contents() is passed ‘1’ for copyelts, a new array is allocated using ncptl_malloc(); the queue’s internal array is copied to the newly allocated array; and, this new array is returned to the caller. It is the caller’s responsibility to pass the result to ncptl_free() when the array is no longer needed. If ncptl_queue_contents() is passed ‘0’ for copyelts, a pointer to the queue’s internal array is returned without first copying it. This pointer should not be passed to ncptl_free() as it is still needed by queue.

Function: ncptl_int ncptl_queue_length (NCPTL_QUEUE *queue)

Return the number of elements in queue queue.

Function: void ncptl_queue_empty (NCPTL_QUEUE *queue)

Empty a queue, freeing the memory that had been allocated for its elements. Queue contents returned by ncptl_queue_contents() with copyelts set to ‘0’ are also invalidated. The queue itself can continue to be used and should be deallocated with ncptl_free() (see Memory-allocation functions) when no longer needed.