1ALL_QUEUE(3) LAM INTERNALS ALL_QUEUE(3)
2
6 all_queue, all_squeue - general purpose queue management package (LAM)
7
9 #include <all_queue.h>
10 QUEUE *aq_init (int size, int elemsize);
12 int aq_delete (QUEUE *aqd);
13 int aq_expand (QUEUE *aqd, int newsize);
14 int aq_insert (QUEUE *aqd, void *elem);
15 int aq_shove (QUEUE *aqd, void *elem);
16 int aq_count (QUEUE *aqd);
17 int aq_size (QUEUE *aqd);
18 void *aq_find (QUEUE *aqd);
19 void aq_free (QUEUE *aqd);
20 SQUEUE *aqs_init (int size, int elemsize, void *queue,
22 SQUEUE *aqsd);
23 int aqs_delete (SQUEUE *aqsd);
24 int aqs_insert (SQUEUE *aqsd, void *elem);
25 int aqs_count (SQUEUE *aqsd);
26 int aqs_size (SQUEUE *aqsd);
27 void *aqs_find (SQUEUE *aqsd);
28
30 The all_queue and all_squeue packages provide general purpose queue
31 management. They differ only in the way memory is allocated for a
32 queue. The dynamic package, all_queue, obtains memory from malloc(3)
33 whenever a new queue is created or its size expanded and returns memory
34 with free(3) whenever a queue is destroyed. The static package,
35 all_squeue, requires that the caller provide memory for the maximum
36 number of queue entries when the queue is first created. Functions
37 that operate on a dynamic queue are named aq_* and functions that oper‐
38 ate on a static queue are named aqs_*.
39 A queue is created and initialized with the aq_init() or aqs_init()
41 functions which both return a pointer to a queue descriptor, typedef
42 QUEUE or SQUEUE respectively. The queue descriptor pointer is used in
43 all subsequent queue operation functions. In the static function,
44 aqs_init(), the caller supplies space not only for the maximum number
45 of queue entries, but also for the queue descriptor.
46 A dynamic queue is freed with the aq_free() function. A static queue
48 is simply forgotten, since the caller is responsible for all the memory
49 involved. Allocating the space for a static queue is straight forward.
50 The user needs to allocate the queue array queue which has size
51 entries, each of which is a user-defined structure of size elemsize.
52 An example of how to allocate space for a static queue is given below:
53 struct myelement queue[31];
55 SQUEUE aqsd;
56 #define ELEMSIZE sizeof(struct myelement)
57 aqs_init(31, ELEMSIZE, queue, &aqsd);
58 Thirty-one elements of type myelement are allocated and named queue.
60 Dynamic Queue Operators
62 The following functions operate on dynamic queues:
63 aq_init() Allocate and initialize a dynamic queue. A queue
65 descriptor pointer is returned, but the null pointer is
66 returned if allocation fails. The caller supplies the
67 total number of entries in the queue and the size of
68 each element.
69 aq_delete() Delete the element located at the top of the queue. The
71 function returns -1 and sets errno to EDELETE if the
72 given queue is empty.
73 aq_insert() Insert a new element at the end of the queue. The call‐
75 er prepares and supplies a pointer to the new element.
76 The function copies the contents of the caller supplied
77 element into the appropriate space in the queue. The
78 caller can reuse the element. The function returns -1
79 and sets errno to EFULL if the queue has no empty slots
80 to store the element.
81 aq_shove() Like aq_insert(), insert an element at the end of the
83 queue. If the queue is full it is expanded by doubling
84 its size and then the element is inserted at the end of
85 the queue.
86 aq_free() Free all allocated memory in a dynamic queue including
88 the queue descriptor. The queue is effectively blown
89 away. The queue descriptor pointer is no longer valid.
90 aq_find() Find the element at the top of the queue. A pointer to
92 the found element is returned, or the null pointer if no
93 element is found.
94 aq_count() A count of all elements in a given queue is returned.
96 aq_size() The size of the given queue is returned.
98 aq_expand() Expand the size of a dynamic queue in order to accomo‐
100 date more elements. The caller provides the desired new
101 queue size. The new size has to be larger than that of
102 the current queue. The function returns -1 if it fails
103 to expand the queue, leaving the initial queue unmodi‐
104 fied.
105 Static Queue Operators
107 The static queue functions are very similar. The differences are
108 listed below.
109 aqs_init() As explained above, this function requires the caller to
111 allocate all the memory used by the queue and the queue
112 descriptor.
113 aqs_free() This function does not exist.
115 aqs_shove() This function does not exist.
117 aqs_expand() This function does not exist.
119
121 all_hash(3), all_list(3)
122LAM 7.1.2 March, 2006 ALL_QUEUE(3)