ALL_QUEUE(3) LAM INTERNALS ALL_QUEUE(3)NAME
all_queue, all_squeue - general purpose queue management package (LAM)
SYNOPSIS
#include <all_queue.h>
QUEUE *aq_init (int size, int elemsize);
int aq_delete (QUEUE *aqd);
int aq_expand (QUEUE *aqd, int newsize);
int aq_insert (QUEUE *aqd, void *elem);
int aq_shove (QUEUE *aqd, void *elem);
int aq_count (QUEUE *aqd);
int aq_size (QUEUE *aqd);
void *aq_find (QUEUE *aqd);
void aq_free (QUEUE *aqd);
SQUEUE *aqs_init (int size, int elemsize, void *queue,
SQUEUE *aqsd);
int aqs_delete (SQUEUE *aqsd);
int aqs_insert (SQUEUE *aqsd, void *elem);
int aqs_count (SQUEUE *aqsd);
int aqs_size (SQUEUE *aqsd);
void *aqs_find (SQUEUE *aqsd);
DESCRIPTION
The all_queue and all_squeue packages provide general purpose queue
management. They differ only in the way memory is allocated for a
queue. The dynamic package, all_queue, obtains memory from malloc(3)
whenever a new queue is created or its size expanded and returns memory
with free(3) whenever a queue is destroyed. The static package,
all_squeue, requires that the caller provide memory for the maximum
number of queue entries when the queue is first created. Functions
that operate on a dynamic queue are named aq_* and functions that oper‐
ate on a static queue are named aqs_*.
A queue is created and initialized with the aq_init() or aqs_init()
functions which both return a pointer to a queue descriptor, typedef
QUEUE or SQUEUE respectively. The queue descriptor pointer is used in
all subsequent queue operation functions. In the static function,
aqs_init(), the caller supplies space not only for the maximum number
of queue entries, but also for the queue descriptor.
A dynamic queue is freed with the aq_free() function. A static queue
is simply forgotten, since the caller is responsible for all the memory
involved. Allocating the space for a static queue is straight forward.
The user needs to allocate the queue array queue which has size
entries, each of which is a user-defined structure of size elemsize.
An example of how to allocate space for a static queue is given below:
struct myelement queue[31];
SQUEUE aqsd;
#define ELEMSIZE sizeof(struct myelement)
aqs_init(31, ELEMSIZE, queue, &aqsd);
Thirty-one elements of type myelement are allocated and named queue.
Dynamic Queue Operators
The following functions operate on dynamic queues:
aq_init() Allocate and initialize a dynamic queue. A queue
descriptor pointer is returned, but the null pointer is
returned if allocation fails. The caller supplies the
total number of entries in the queue and the size of
each element.
aq_delete() Delete the element located at the top of the queue. The
function returns -1 and sets errno to EDELETE if the
given queue is empty.
aq_insert() Insert a new element at the end of the queue. The call‐
er prepares and supplies a pointer to the new element.
The function copies the contents of the caller supplied
element into the appropriate space in the queue. The
caller can reuse the element. The function returns -1
and sets errno to EFULL if the queue has no empty slots
to store the element.
aq_shove() Like aq_insert(), insert an element at the end of the
queue. If the queue is full it is expanded by doubling
its size and then the element is inserted at the end of
the queue.
aq_free() Free all allocated memory in a dynamic queue including
the queue descriptor. The queue is effectively blown
away. The queue descriptor pointer is no longer valid.
aq_find() Find the element at the top of the queue. A pointer to
the found element is returned, or the null pointer if no
element is found.
aq_count() A count of all elements in a given queue is returned.
aq_size() The size of the given queue is returned.
aq_expand() Expand the size of a dynamic queue in order to accomo‐
date more elements. The caller provides the desired new
queue size. The new size has to be larger than that of
the current queue. The function returns -1 if it fails
to expand the queue, leaving the initial queue unmodi‐
fied.
Static Queue Operators
The static queue functions are very similar. The differences are
listed below.
aqs_init() As explained above, this function requires the caller to
allocate all the memory used by the queue and the queue
descriptor.
aqs_free() This function does not exist.
aqs_shove() This function does not exist.
aqs_expand() This function does not exist.
SEE ALSOall_hash(3), all_list(3)LAM 7.1.2 March, 2006 ALL_QUEUE(3)
