Linux Certif

Toute la documentation sur la certification Linux LPI

all_queue

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.

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 ALSO

all_hash(3), all_list(3)