all_queue(3) - Linux man page

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 operate 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 caller 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 accomodate 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 unmodified.

Static Queue Operators

The static queue functions are very similar. The differences are listed below.