ALL_QUEUE (3)

SYNOPSIS

.75i 1.25i
#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. 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. 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) - man3/scandir 3 ' " ' " Copyright(c) 1993 The Regents of the University of California ' " Copyright(c) 1994-1996 Sun Microsystems Inc ' " ' " See the file "license terms" for information on usage and redistribution ' " of this file and for a DISCLAIMER OF ALL WARRANTIES ' " ' " RCS: @(#) $Id: AppInit 3 v 1 2 1998/09/14 18:39:46 stanton Exp $ ' " ' " The definitions below are for supplemental macros used in Tcl/Tk ' " manual entries ' " ' " AP type name in/out ?indent? ' " Start paragraph describing an argument to a library procedure ' " type is type of argument(int etc ) in/out is either "in" "out" ' " or "in/out" to describe whether procedure reads or modifies arg ' " and indent is equivalent to second arg of IP(shouldn't ever be ' " needed; use AS below instead) ' " ' " AS ?type? ?name? ' " Give maximum sizes of arguments for setting tab stops Type and ' " name are examples of largest possible arguments that will be passed ' " to AP later If args are omitted default tab stops are used ' " ' " BS ' " Start box enclosure From here until next BE everything will be ' " enclosed in one large box ' " ' " BE ' " End of box enclosure ' " ' " CS ' " Begin code excerpt ' " ' " CE ' " End code excerpt ' " ' " VS ?version? ?br? ' " Begin vertical sidebar for use in marking newly-changed parts ' " of man pages The first argument is ignored and used for recording ' " the version when the VS was added so that the sidebars can be ' " found and removed when they reach a certain age If another argument ' " is present then a line break is forced before starting the sidebar ' " ' " VE ' " End of vertical sidebar ' " ' " DS ' " Begin an indented unfilled display ' " ' " DE ' " End of indented unfilled display ' " ' " SO ' " Start of list of standard options for a Tk widget The ' " options follow on successive lines in four columns separated ' " by tabs ' " ' " SE ' " End of list of standard options for a Tk widget ' " ' " OP cmdName dbName dbClass ' " Start of description of a specific option cmdName gives the ' " option's name as specified in the class command dbName gives ' " the option's name in the option database and dbClass gives ' " the option's class in the option database ' " ' " UL arg1 arg2 ' " Print arg1 underlined then print arg2 normally ' " ' " RCS: @(#) $Id: man macros v 1 2 1998/09/14 18:39:54 stanton Exp $ ' " ' " # Set up traps and other miscellaneous stuff for Tcl/Tk man pages t wh -1 3i ^B ^l n( l b ' " # Start an argument description AP !" $4"" TP $4 { !" $2"" TP n()Cu 15