NAME
Array —
A simple static queue data
structure.
SYNOPSIS
#include
<Queue.h>
Queue *
QueueCreate(size_t);
void
QueueFree(Array
*);
int
QueuePush(Queue
*, void *);
void *
QueuePop(Queue
*);
void *
QueuePeek(Queue
*);
int
QueueFull(Queue
*);
int
QueueEmpty(Queue
*);
DESCRIPTION
These functions implement a simple queue data structure that is statically sized. This implementation does not actually store the values of the items in it; it only stores pointers to the data. As such, you will still have to manually maintain all your data. The advantage of this is that these functions don't have to copy data, and thus don't care how big the data is. Furthermore, arbitrary data can be stored in the queue.
This queue implementation operates on the heap. It is a circular queue, and it does not grow as it is used. Once the size is set, the queue never gets any bigger.
These functions operate on a queue structure which is opaque to the caller.
QueueCreate()
and
QueueFree()
allocate and deallocate a queue, respectively. Note that
QueueFree() does not free any of the values stored
in the queue; it is the caller's job to manage the memory for each item.
Typically, the caller would dequeue all the items in the queue and free them
before freeing the queue itself.
QueuePush()
and
QueuePop()
are the main functions used to modify the array. They enqueue and dequeue
elements from the queue structure, respectively.
QueuePeek()
simply returns the pointer that is next up in the queue without actually
discarding it, such that the next call to
QueuePeek() or QueuePop()
return the same pointer.
QueueFull()
and
QueueEmpty()
return a boolean value that indicates whether or not the queue is full or
empty, respectively.
RETURN VALUES
QueueCreate() returns a queue structure,
or NULL if there was a memory allocation error.
QueuePush() as well as
QueueFull() and QueueEmpty()
all return boolean values. In the case of
QueuePush() whether or not the push was actually
successful is returned. This will only happen if the queue is already full,
or a NULL pointer is passed.
QueuePop() and
QueuePeek() both return caller-managed pointers that
would have been at some point pushed into the queue with the
QueuePush() function. They may also return
NULL if the queue is empty.