1 /* a fifo queue that never fills.
2 * Copyright (C) 2005 Elwood C. Downey ecdowney@clearskyinstitute.com
3 * includes standalone commandline test program, see below.
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18
19 */
20
21 /** \file fq.c
22 \brief a fifo queue that never fills.
23
24 Generic FIFO Queue.
25
26 an FQ is a FIFO list of pointers to void, each called an "element".
27 elements are added at q[head]. there are (nq) elements in the list. the
28 element to be removed next is q[head-nq]. there are (head-nq) empty slots
29 at the front of the q array. there are (nmem-head) elements available at
30 the end. if the head reaches the end, existing enties are slid to the front
31 of the array and total memory is adjusted up or down as required.
32
33 example:
34
35 <-------------------- nmem = 17 --------------------------------->
36 <-- head - nq = 6 ---> <-- nq = 4 --> <---- nmem - head = 7 -->
37 ---------------------------------------------------------------------
38 | | | | | | | x | x | x | x | | | | | | | |
39 ---------------------------------------------------------------------
40 0 1 2 3 4 5 6 7 8 9 ^
41 head = 10
42
43 \author Elwood Downey
44 */
45
46 #include "fq.h"
47
48 #include <stdlib.h>
49 #include <string.h>
50
51 struct _FQ
52 {
53 void **q; /* malloced array of (void *) */
54 int nq; /* number of elements on queue */
55 int head; /* index into q[] of next empty spot */
56 int nmem; /* number of total slots in q[] */
57 int grow; /* n elements to grow when out of room*/
58 };
59
60 /* default memory managers, override with setMemFuncsFQ() */
61 static void *(*fqmalloc)(size_t size) = malloc;
62 static void *(*fqrealloc)(void *ptr, size_t size) = realloc;
63 static void (*fqfree)(void *ptr) = free;
64
65 static void chkFQ(FQ *q);
66
67 /* return pointer to a new FQ, or NULL if no more memory.
68 * grow is an efficiency hint of the number of elements to grow when out of
69 * room, nothing terrible happens if it is wrong.
70 */
newFQ(int grow)71 FQ *newFQ(int grow)
72 {
73 FQ *q = (FQ *)(*fqmalloc)(sizeof(FQ));
74 memset(q, 0, sizeof(FQ));
75 q->q = (*fqmalloc)(1); /* seed for realloc */
76 q->grow = grow > 0 ? grow : 1;
77 return (q);
78 }
79
80 /* delete a FQ no longer needed */
delFQ(FQ * q)81 void delFQ(FQ *q)
82 {
83 (*fqfree)(q->q); /* guaranteed set in newFQ() */
84 (*fqfree)((void *)q);
85 }
86
87 /* push an element onto the given FQ */
pushFQ(FQ * q,void * e)88 void pushFQ(FQ *q, void *e)
89 {
90 chkFQ(q);
91 q->q[q->head++] = e;
92 q->nq++;
93 }
94
95 /* pop and return the next element in the given FQ, or NULL if empty */
popFQ(FQ * q)96 void *popFQ(FQ *q)
97 {
98 return (q->nq > 0 ? q->q[q->head - q->nq--] : NULL);
99 }
100
101 /* return next element in the given FQ leaving it on the q, or NULL if empty */
peekFQ(FQ * q)102 void *peekFQ(FQ *q)
103 {
104 return (peekiFQ(q, 0));
105 }
106
107 /* return ith element from head of the given FQ.
108 * this can be used for iteration as:
109 * for (i = 0; i < nFQ(q); i++)
110 * void *e = peekiFQ(q,i);
111 */
peekiFQ(FQ * q,int i)112 void *peekiFQ(FQ *q, int i)
113 {
114 return (q->nq > 0 ? q->q[q->head - q->nq + i] : NULL);
115 }
116
117 /* return the number of elements in the given FQ */
nFQ(FQ * q)118 int nFQ(FQ *q)
119 {
120 return (q->nq);
121 }
122
123 /* install new version of malloc/realloc/free.
124 * N.B. don't call after first use of any other FQ function
125 */
setMemFuncsFQ(void * (* newmalloc)(size_t size),void * (* newrealloc)(void * ptr,size_t size),void (* newfree)(void * ptr))126 void setMemFuncsFQ(void *(*newmalloc)(size_t size), void *(*newrealloc)(void *ptr, size_t size),
127 void (*newfree)(void *ptr))
128 {
129 fqmalloc = newmalloc;
130 fqrealloc = newrealloc;
131 fqfree = newfree;
132 }
133
134 /* insure q can hold one more element */
chkFQ(FQ * q)135 static void chkFQ(FQ *q)
136 {
137 int infront;
138
139 /* done if still room at end */
140 if (q->nmem > q->head)
141 return;
142
143 /* move list to front */
144 infront = q->head - q->nq;
145 memmove(q->q, &q->q[infront], q->nq * sizeof(void *));
146 q->head -= infront;
147
148 /* realloc to minimum number of grow-sized chunks required */
149 q->nmem = q->grow * (q->head / q->grow + 1);
150 q->q = (*fqrealloc)(q->q, q->nmem * sizeof(void *));
151 }
152
153 #if defined(TEST_FQ)
154
155 /* to build a stand-alone commandline test program:
156 * cc -DTEST_FQ -o fq fq.c
157 * run ./fq to test push/pop/peek and watch the queue after each operation.
158 * the queue test elements are char, please excuse the ugly casts.
159 */
160
161 #include <stdio.h>
162
163 /* draw a simple graphical representation of the given FQ */
prFQ(FQ * q)164 static void prFQ(FQ *q)
165 {
166 int i;
167
168 /* print the q, empty slots print as '.' */
169 for (i = 0; i < q->nmem; i++)
170 {
171 if (i >= q->head - q->nq && i < q->head)
172 printf("%c", (char)(int)q->q[i]);
173 else
174 printf(".");
175 }
176
177 /* add right-justified stats */
178 printf("%*s nmem = %2d head = %2d nq = %2d\n", 50 - i, "", q->nmem, q->head, q->nq);
179 }
180
main(int ac,char * av[])181 int main(int ac, char *av[])
182 {
183 FQ *q = newFQ(8);
184 int c, e = -1;
185 void *p;
186
187 printf("Commands:\n");
188 printf(" P = push a letter a-z\n");
189 printf(" p = pop a letter\n");
190 printf(" k = peek into queue\n");
191
192 while ((c = fgetc(stdin)) != EOF)
193 {
194 switch (c)
195 {
196 case 'P':
197 pushFQ(q, (void *)('a' + (e = (e + 1) % 26)));
198 prFQ(q);
199 break;
200 case 'p':
201 p = popFQ(q);
202 if (p)
203 printf("popped %c\n", (char)(int)p);
204 else
205 printf("popped empty q\n");
206 prFQ(q);
207 break;
208 case 'k':
209 p = peekFQ(q);
210 if (p)
211 printf("peeked %c\n", (char)(int)p);
212 else
213 printf("peeked empty q\n");
214 prFQ(q);
215 break;
216 default:
217 break;
218 }
219 }
220
221 return (0);
222 }
223 #endif /* TEST_FQ */
224