Mercurial > almixer_isolated
annotate CircularQueue.h @ 71:36644b1b940b
Removed use of dllimport for Windows.
Johnson Lin reported that he was getting warnings about it. I think the problem is that I didn't handle the case where you compile the files into your project or statically link. In this case you don't want dllexport or dllimport. From what I read, dllimport is optional (an optimization hint). Since this is becoming a nuisance, I rather just remove it rather than require another build flag.
author | Eric Wing <ewing . public |-at-| gmail . com> |
---|---|
date | Wed, 20 Jun 2012 10:46:03 -0700 |
parents | 516da6d93534 |
children | 398d1cb12448 |
rev | line source |
---|---|
0 | 1 /* |
2 CircularQueue | |
2
279d0427ef26
Overhaul prep for first public release.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
1
diff
changeset
|
3 Copyright (C) 2002 Eric Wing <ewing . public @ playcontrol.net> |
0 | 4 |
5 This library is free software; you can redistribute it and/or | |
6 modify it under the terms of the GNU Library General Public | |
7 License as published by the Free Software Foundation; either | |
8 version 2 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 Library General Public License for more details. | |
14 | |
15 You should have received a copy of the GNU Library General Public | |
16 License along with this library; if not, write to the Free | |
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
18 */ | |
19 | |
20 | |
21 #ifndef C_CIRCULAR_QUEUE_H | |
22 #define C_CIRCULAR_QUEUE_H | |
23 | |
24 /* Set up for C function definitions, even when using C++ */ | |
25 #ifdef __cplusplus | |
26 extern "C" { | |
27 #endif | |
28 | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
29 #ifndef DOXYGEN_SHOULD_IGNORE_THIS |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
30 /** @cond DOXYGEN_SHOULD_IGNORE_THIS */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
31 |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
32 /* Note: For Doxygen to produce clean output, you should set the |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
33 * PREDEFINED option to remove C_CIRCULAR_QUEUE_DECLSPEC, C_CIRCULAR_QUEUE_CALL, and |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
34 * the DOXYGEN_SHOULD_IGNORE_THIS blocks. |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
35 * PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 C_CIRCULAR_QUEUE_DECLSPEC= C_CIRCULAR_QUEUE_CALL= |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
36 */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
37 |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
38 /** Windows needs to know explicitly which functions to export in a DLL. */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
39 #if defined(_WIN32) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
40 #if defined(C_CIRCULAR_QUEUE_BUILD_LIBRARY) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
41 #define C_CIRCULAR_QUEUE_DECLSPEC __declspec(dllexport) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
42 #endif |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
43 #else |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
44 #if defined(C_CIRCULAR_QUEUE_BUILD_LIBRARY) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
45 #if defined (__GNUC__) && __GNUC__ >= 4 |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
46 #define C_CIRCULAR_QUEUE_DECLSPEC __attribute__((visibility("default"))) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
47 #else |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
48 #define C_CIRCULAR_QUEUE_DECLSPEC |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
49 #endif |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
50 #else |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
51 #define C_CIRCULAR_QUEUE_DECLSPEC |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
52 #endif |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
53 #endif |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
54 |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
55 /* For Windows, by default, use the C calling convention */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
56 #if defined(_WIN32) |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
57 #define C_CIRCULAR_QUEUE_CALL __cdecl |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
58 #else |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
59 #define C_CIRCULAR_QUEUE_CALL |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
60 #endif |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
61 |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
62 /** @endcond DOXYGEN_SHOULD_IGNORE_THIS */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
63 #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ |
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
64 |
0 | 65 /** |
66 * @file | |
67 * This is a C-based Circular queue class. | |
68 * This class provides very simple circular queue functionality, | |
69 * with an API similar to the C++ STL queue class. | |
70 * Currently, a queue cannot be resized. | |
71 * Because C doesn't do templates and I really don't want | |
72 * to write my own polymorphism, you must select the proper queue | |
73 * for your data types. | |
74 * I currently provide an unisigned int version | |
75 * and a void* version. The void* version will let you use any type, | |
76 * but remember that you are responsible for casting and maintaining | |
77 * your own type safety. I have found the unsigned int version to be | |
78 * very useful because if you have a map somewhere that associates | |
79 * unique identifier numbers to data (e.g. OpenGL displaylists/textures), | |
80 * then you can just deal with the id numbers and don't have to deal with | |
81 * the casting and typesafety issues. I recommend you don't overlook the | |
82 * usefulness of this version. | |
83 * | |
84 * @warning Do not mix the CircularQueues created from the different versions. | |
85 * They are incompatible. Use only CircularQueueUnsignedInt objects with | |
86 * CircularQueueUnsignedInt_* functions, etc. | |
87 * | |
88 * Example Usage: | |
89 * @code | |
90 * CircularQueueUnsignedInt* myqueue; | |
91 * unsigned int ret_val; | |
92 * | |
93 * myqueue = CircularQueueUnsignedInt_CreateQueue(3); | |
94 * if(NULL == myqueue) | |
95 * { | |
96 * fprintf(stderr, "Error, could not create queue\n"); | |
97 * return 0; | |
98 * } | |
99 * | |
100 * | |
101 * ret_val = CircularQueueUnsignedInt_PushBack(myqueue, 1); | |
102 * ret_val = CircularQueueUnsignedInt_PushBack(myqueue, 2); | |
103 * ret_val = CircularQueueUnsignedInt_PushBack(myqueue, 3); | |
104 * if(0 == ret_val) | |
105 * { | |
106 * fprintf(stderr, "Error, Could not pushback\n"); | |
107 * exit(1); | |
108 * } | |
109 * | |
110 * ret_val = CircularQueueUnsignedInt_PopBack(myqueue); | |
111 * if(0 == ret_val) | |
112 * { | |
113 * fprintf(stderr, "Error, Could not popback\n"); | |
114 * exit(2); | |
115 * } | |
116 * | |
117 * fprintf(stderr, "Testing queue, should have 1,2\n"); | |
118 * CircularQueueUnsignedInt_Print(myqueue); | |
119 * | |
120 * ret_val = CircularQueueUnsignedInt_PushFront(myqueue, 4); | |
121 * if(0 == ret_val) | |
122 * { | |
123 * fprintf(stderr, "Error, Could not pushfront\n"); | |
124 * exit(1); | |
125 * } | |
126 * fprintf(stderr, "Testing queue, should have 4,1,2\n"); | |
127 * CircularQueueUnsignedInt_Print(myqueue); | |
128 * | |
129 * @endcode | |
130 */ | |
131 | |
1 | 132 /* This is a trick I picked up from Lua. Doing the typedef separately |
133 * (and I guess before the definition) instead of a single | |
134 * entry: typedef struct {...} YourName; seems to allow me | |
135 * to use forward declarations. Doing it the other way (like SDL) | |
136 * seems to prevent me from using forward declarions as I get conflicting | |
137 * definition errors. I don't really understand why though. | |
138 */ | |
139 typedef struct CircularQueueUnsignedInt CircularQueueUnsignedInt; | |
0 | 140 /** |
141 * This is the essentially the CircularQueue object. | |
142 * This contains all the data associated with a CircularQueue instance. | |
143 * This version is for unsigned int data types. In the future, I suppose | |
144 * I could add a void* data type at the very least and maybe some | |
145 * other data types. | |
146 * This should be considered an opaque data type. | |
147 */ | |
1 | 148 struct CircularQueueUnsignedInt |
0 | 149 { |
150 unsigned int maxSize; /**< Max size of the queue. */ | |
151 unsigned int currentSize; /**< Current number of entries in the queue. */ | |
152 unsigned int headIndex; /**< The index of where the current head is. */ | |
153 unsigned int tailIndex; /**< The index of where the current tail is. */ | |
154 unsigned int* internalQueue; /**< The array representing the queue. */ | |
1 | 155 }; |
0 | 156 |
157 /** | |
158 * This creates a new CircularQueue (for unsigned int) instance. | |
159 * This will create a new circular queue instance which holds | |
160 * unsigned int's in its queue. | |
161 * | |
162 * @note This implementation does not allow a circular queue to be resized. | |
163 * | |
164 * @param max_size This specifies the maximum number of elements the circular | |
165 * can hold. | |
166 * | |
167 * @return Returns a pointer to a CircularQueue which is the | |
168 * instance variable (if successful) or NULL on failure. | |
169 * | |
170 * @see CircularQueueUnsignedInt_FreeQueue | |
171 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
172 extern C_CIRCULAR_QUEUE_DECLSPEC CircularQueueUnsignedInt* C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_CreateQueue(unsigned int max_size); |
0 | 173 |
174 /** | |
175 * This destroys a CircularQueue instance. | |
176 * This will destroy the memory associated with the circular queue instance. | |
177 * Whenever you create a CircularQueue instance, you should always to | |
178 * remember to balance it with a FreeQueue. | |
179 * | |
180 * @param queue The pointer to the CircularQueue instance. | |
181 * | |
182 * @see CircularQueueUnsignedInt_CreateQueue | |
183 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
184 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_FreeQueue(CircularQueueUnsignedInt* queue); |
0 | 185 |
186 /** | |
187 * This pushes a new value into the back of the queue. | |
188 * If the queue is full, the function will fail and return 0. | |
189 * | |
190 * @param queue The pointer to the CircularQueue instance. | |
191 * @param value The value you want to push into the queue. | |
192 * | |
193 * @return Returns 1 on success, or 0 on failure. | |
194 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
195 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_PushBack(CircularQueueUnsignedInt* queue, unsigned int value); |
0 | 196 |
197 /** | |
198 * This pushes a new value into the front of the queue. | |
199 * If the queue is full, the function will fail and return 0. | |
200 * | |
201 * @param queue The pointer to the CircularQueue instance. | |
202 * @param value The value you want to push into the queue. | |
203 * | |
204 * @return Returns 1 on success, or 0 on failure. | |
205 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
206 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_PushFront(CircularQueueUnsignedInt* queue, unsigned int value); |
0 | 207 |
208 /** | |
209 * This removes the value at the front of the queue. | |
210 * If the queue is empty, the function will return 0. | |
211 * Note that this function does not return the value popped, but | |
212 * an error flag. If you need the value, you must call Front() | |
213 * to retrieve the value before popping it. | |
214 * | |
215 * @param queue The pointer to the CircularQueue instance. | |
216 * | |
217 * @return Returns 1 on success, or 0 on failure. | |
218 * @see CircularQueueUnsignedInt_Front | |
219 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
220 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_PopFront(CircularQueueUnsignedInt* queue); |
0 | 221 |
222 /** | |
223 * This removes the value at the back of the queue. | |
224 * If the queue is empty, the function will return 0. | |
225 * Note that this function does not return the value popped, but | |
226 * an error flag. If you need the value, you must call Back() | |
227 * to retrieve the value before popping it. | |
228 * | |
229 * @param queue The pointer to the CircularQueue instance. | |
230 * | |
231 * @return Returns 1 on success, or 0 on failure. | |
232 * @see CircularQueueUnsignedInt_Back | |
233 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
234 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_PopBack(CircularQueueUnsignedInt* queue); |
0 | 235 |
236 /** | |
237 * This gets the value at the front of the queue. | |
238 * If the queue is empty, the value returned will be 0. | |
239 * Because this 0 return value is ambiguous because it could also could | |
240 * be a legitimate value in the queue, if you need more robust error | |
241 * checking for if the queue is empty, you should get the size of the | |
242 * queue using the Size() function. | |
243 * | |
244 * @param queue The pointer to the CircularQueue instance. | |
245 * | |
246 * @return Returns the value stored at the queue or 0 if the queue is empty | |
247 * (or if there is an error). | |
248 * | |
249 * @see CircularQueueUnsignedInt_Size | |
250 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
251 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_Front(CircularQueueUnsignedInt* queue); |
0 | 252 |
253 /** | |
254 * This gets the value at the back of the queue. | |
255 * If the queue is empty, the value returned will be 0. | |
256 * Because this 0 return value is ambiguous because it could also could | |
257 * be a legitimate value in the queue, if you need more robust error | |
258 * checking for if the queue is empty, you should get the size of the | |
259 * queue using the Size() function. | |
260 * | |
261 * @param queue The pointer to the CircularQueue instance. | |
262 * | |
263 * @return Returns the value stored at the queue or 0 if the queue is empty | |
264 * (or 0 if there is an error). | |
265 * | |
266 * @see CircularQueueUnsignedInt_Size | |
267 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
268 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_Back(CircularQueueUnsignedInt* queue); |
0 | 269 |
270 /** | |
271 * This gets the current number of entries that are in the queue. | |
272 * This is number is not to be confused with the MaxSize. | |
273 * | |
274 * @param queue The pointer to the CircularQueue instance. | |
275 * | |
276 * @return Returns the number of entries currently in queue, or 0 if | |
277 * there is an error. | |
278 * | |
279 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
280 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_Size(CircularQueueUnsignedInt* queue); |
0 | 281 |
282 /** | |
283 * This gets the maximum number of entries that are allowed in the queue at | |
284 * a given time. | |
285 * This is the number that you used in the CreateQueue function. | |
286 * | |
287 * @param queue The pointer to the CircularQueue instance. | |
288 * | |
289 * @return Returns the maximum number of entries allowed in the queue. | |
290 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
291 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_MaxSize(CircularQueueUnsignedInt* queue); |
0 | 292 /** |
293 * This empties the entire queue. | |
294 * This will remove all entries that are in the queue. | |
295 * This does not destroy any memory. Use FreeQueue() to actually destroy | |
296 * the queue. | |
297 * | |
298 * @param queue The pointer to the CircularQueue instance. | |
299 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
300 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_Clear(CircularQueueUnsignedInt* queue); |
0 | 301 |
302 /** | |
303 * This is a debugging function that will print all the elements in the | |
304 * queue to stderr. | |
305 * This function is provided as convenience, but should not be considered | |
306 * as part of the standard API. Treat this function as deprecated | |
307 * as it's implementation may change or be removed entirely. | |
308 * | |
309 * @param queue The pointer to the CircularQueue instance. | |
310 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
311 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_Print(CircularQueueUnsignedInt* queue); |
0 | 312 |
1 | 313 /** |
314 * This returns the element located at the specified index, | |
315 * where index=0 represents the head/front of the queue. | |
316 * | |
317 * @param queue The pointer to the CircularQueue instance. | |
318 * @param the_index The index of the element you want where 0 represents the | |
319 * head/front of the queue and Size-1 is the back. | |
320 * | |
321 * @return Returns the value located at the index on success, or 0 on failure. | |
322 * Be careful to not to confuse an error for a legitmate 0 value. | |
323 * Any index from 0 to Size-1 (where Size>0) will be a valid index. | |
324 * | |
325 * This example traverses through the whole queue and prints out each value. | |
326 * @code | |
327 * fprintf(stderr, "Queue: "); | |
328 * for(i=0;i<CircularQueueUnsignedInt_Size(xValueQueue);i++) | |
329 * { | |
330 * ret_val = CircularQueueUnsignedInt_ValueAtIndex(xValueQueue, i); | |
331 * fprintf(stderr, "%d ", ret_val); | |
332 * | |
333 * } | |
334 * fprintf(stderr, "\n"); | |
5
8cb13d89451a
Doxygen support and fixes.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
2
diff
changeset
|
335 * @endcode |
1 | 336 * |
337 * @note The implementation uses a modulo operation to compute the index, so | |
338 * this may not be the speediest operation in a tight loop. | |
339 * This implementation was not optimized for random access, though it still | |
340 * is technically O(1). | |
341 * | |
342 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
343 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueUnsignedInt_ValueAtIndex(CircularQueueUnsignedInt* queue, unsigned int the_index); |
0 | 344 |
1 | 345 |
346 /* This is a trick I picked up from Lua. Doing the typedef separately | |
347 * (and I guess before the definition) instead of a single | |
348 * entry: typedef struct {...} YourName; seems to allow me | |
349 * to use forward declarations. Doing it the other way (like SDL) | |
350 * seems to prevent me from using forward declarions as I get conflicting | |
351 * definition errors. I don't really understand why though. | |
352 */ | |
353 typedef struct CircularQueueVoid CircularQueueVoid; | |
0 | 354 /** |
355 * This is the essentially the CircularQueue object. | |
356 * This contains all the data associated with a CircularQueue instance. | |
357 * This version is for unsigned int data types. In the future, I suppose | |
358 * I could add a void* data type at the very least and maybe some | |
359 * other data types. | |
360 * This should be considered an opaque data type. | |
361 */ | |
1 | 362 struct CircularQueueVoid |
0 | 363 { |
364 unsigned int maxSize; /**< Max size of the queue. */ | |
365 unsigned int currentSize; /**< Current number of entries in the queue. */ | |
366 unsigned int headIndex; /**< The index of where the current head is. */ | |
367 unsigned int tailIndex; /**< The index of where the current tail is. */ | |
368 void** internalQueue; /**< The array representing the queue. */ | |
1 | 369 }; |
0 | 370 |
371 /** | |
372 * This creates a new CircularQueue (for void* ) instance. | |
373 * This will create a new circular queue instance which holds | |
374 * unsigned int's in its queue. | |
375 * | |
376 * @note This implementation does not allow a circular queue to be resized. | |
377 * | |
378 * @param max_size This specifies the maximum number of elements the circular | |
379 * can hold. | |
380 * | |
381 * @return Returns a pointer to a CircularQueue which is the | |
382 * instance variable (if successful) or NULL on failure. | |
383 * | |
384 * @see CircularQueueVoid_FreeQueue | |
385 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
386 extern C_CIRCULAR_QUEUE_DECLSPEC CircularQueueVoid* C_CIRCULAR_QUEUE_CALL CircularQueueVoid_CreateQueue(unsigned int max_size); |
0 | 387 |
388 /** | |
389 * This destroys a CircularQueue instance. | |
390 * This will destroy the memory associated with the circular queue instance. | |
391 * Whenever you create a CircularQueue instance, you should always to | |
392 * remember to balance it with a FreeQueue. | |
393 * | |
394 * @param queue The pointer to the CircularQueue instance. | |
395 * | |
396 * @see CircularQueueVoid_CreateQueue | |
397 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
398 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueVoid_FreeQueue(CircularQueueVoid* queue); |
0 | 399 |
400 /** | |
401 * This pushes a new value into the back of the queue. | |
402 * If the queue is full, the function will fail and return 0. | |
403 * | |
404 * @param queue The pointer to the CircularQueue instance. | |
405 * @param value The value you want to push into the queue. | |
406 * | |
407 * @return Returns 1 on success, or 0 on failure. | |
408 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
409 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_PushBack(CircularQueueVoid* queue, void* value); |
0 | 410 |
411 /** | |
412 * This pushes a new value into the front of the queue. | |
413 * If the queue is full, the function will fail and return 0. | |
414 * | |
415 * @param queue The pointer to the CircularQueue instance. | |
416 * @param value The value you want to push into the queue. | |
417 * | |
418 * @return Returns 1 on success, or 0 on failure. | |
419 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
420 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_PushFront(CircularQueueVoid* queue, void* value); |
0 | 421 |
422 /** | |
423 * This removes the value at the front of the queue. | |
424 * If the queue is empty, the function will return 0. | |
425 * Note that this function does not return the value popped, but | |
426 * an error flag. If you need the value, you must call Front() | |
427 * to retrieve the value before popping it. | |
428 * | |
429 * @param queue The pointer to the CircularQueue instance. | |
430 * | |
431 * @return Returns 1 on success, or 0 on failure. | |
432 * @see CircularQueueVoid_Front | |
433 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
434 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_PopFront(CircularQueueVoid* queue); |
0 | 435 |
436 /** | |
437 * This removes the value at the back of the queue. | |
438 * If the queue is empty, the function will return 0. | |
439 * Note that this function does not return the value popped, but | |
440 * an error flag. If you need the value, you must call Back() | |
441 * to retrieve the value before popping it. | |
442 * | |
443 * @param queue The pointer to the CircularQueue instance. | |
444 * | |
445 * @return Returns 1 on success, or 0 on failure. | |
446 * @see CircularQueueVoid_Back | |
447 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
448 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_PopBack(CircularQueueVoid* queue); |
0 | 449 |
450 /** | |
451 * This gets the value at the front of the queue. | |
452 * If the queue is empty, the value returned will be 0. | |
453 * Because this 0 return value is ambiguous because it could also could | |
454 * be a legitimate value in the queue, if you need more robust error | |
455 * checking for if the queue is empty, you should get the size of the | |
456 * queue using the Size() function. | |
457 * | |
458 * @param queue The pointer to the CircularQueue instance. | |
459 * | |
460 * @return Returns the value stored at the queue or 0 if the queue is empty | |
461 * (or if there is an error). | |
462 * | |
463 * @see CircularQueueVoid_Size | |
464 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
465 extern C_CIRCULAR_QUEUE_DECLSPEC void* C_CIRCULAR_QUEUE_CALL CircularQueueVoid_Front(CircularQueueVoid* queue); |
0 | 466 |
467 /** | |
468 * This gets the value at the back of the queue. | |
469 * If the queue is empty, the value returned will be 0. | |
470 * Because this 0 return value is ambiguous because it could also could | |
471 * be a legitimate value in the queue, if you need more robust error | |
472 * checking for if the queue is empty, you should get the size of the | |
473 * queue using the Size() function. | |
474 * | |
475 * @param queue The pointer to the CircularQueue instance. | |
476 * | |
477 * @return Returns the value stored at the queue or 0 if the queue is empty | |
478 * (or 0 if there is an error). | |
479 * | |
480 * @see CircularQueueVoid_Size | |
481 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
482 extern C_CIRCULAR_QUEUE_DECLSPEC void* C_CIRCULAR_QUEUE_CALL CircularQueueVoid_Back(CircularQueueVoid* queue); |
0 | 483 |
484 /** | |
485 * This gets the current number of entries that are in the queue. | |
486 * This is number is not to be confused with the MaxSize. | |
487 * | |
488 * @param queue The pointer to the CircularQueue instance. | |
489 * | |
490 * @return Returns the number of entries currently in queue, or 0 if | |
491 * there is an error. | |
492 * | |
493 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
494 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_Size(CircularQueueVoid* queue); |
0 | 495 |
496 /** | |
497 * This gets the maximum number of entries that are allowed in the queue at | |
498 * a given time. | |
499 * This is the number that you used in the CreateQueue function. | |
500 * | |
501 * @param queue The pointer to the CircularQueue instance. | |
502 * | |
503 * @return Returns the maximum number of entries allowed in the queue. | |
504 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
505 extern C_CIRCULAR_QUEUE_DECLSPEC unsigned int C_CIRCULAR_QUEUE_CALL CircularQueueVoid_MaxSize(CircularQueueVoid* queue); |
0 | 506 /** |
507 * This empties the entire queue. | |
508 * This will remove all entries that are in the queue. | |
509 * This does not destroy any memory. Use FreeQueue() to actually destroy | |
510 * the queue. | |
511 * | |
512 * @param queue The pointer to the CircularQueue instance. | |
513 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
514 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueVoid_Clear(CircularQueueVoid* queue); |
0 | 515 |
1 | 516 /** |
517 * This is a debugging function that will print all the addresses | |
518 * of elements in the queue to stderr. | |
519 * This function is provided as convenience, but should not be considered | |
520 * as part of the standard API. Treat this function as deprecated | |
521 * as it's implementation may change or be removed entirely. | |
522 * | |
523 * @param queue The pointer to the CircularQueue instance. | |
524 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
525 extern C_CIRCULAR_QUEUE_DECLSPEC void C_CIRCULAR_QUEUE_CALL CircularQueueVoid_Print(CircularQueueVoid* queue); |
1 | 526 |
527 /** | |
528 * This returns the element located at the specified index, | |
529 * where index=0 represents the head/front of the queue. | |
530 * | |
531 * @param queue The pointer to the CircularQueue instance. | |
532 * @param the_index The index of the element you want where 0 represents the | |
533 * head/front of the queue and Size-1 is the back. | |
534 * | |
535 * @return Returns the element located at the index on success, or NULL on failure. | |
536 * Be careful to not to confuse an error for a legitmate NULL value. | |
537 * Any index from 0 to Size-1 (where Size>0) will be a valid index. | |
538 * | |
539 * This example traverses through the whole queue and prints out each value. | |
540 * @code | |
541 * fprintf(stderr, "Queue: "); | |
542 * for(i=0;i<CircularQueueVoid_ValueAtIndex(xValueQueue);i++) | |
543 * { | |
544 * void* ret_val = CircularQueueUnsignedInt_ValueAtIndex(xValueQueue, i); | |
545 * fprintf(stderr, "%x ", ret_val); | |
546 * | |
547 * } | |
548 * fprintf(stderr, "\n"); | |
549 * | |
550 * @note The implementation uses a modulo operation to compute the index, so | |
551 * this may not be the speediest operation in a tight loop. | |
552 * This implementation was not optimized for random access, though it still | |
553 * is technically O(1). | |
554 * | |
555 */ | |
54
516da6d93534
Added explicit symbol visibility markers to support files in ALmixer for public headers so they can be built as a dynamic library if needed.
Eric Wing <ewing@anscamobile.com>
parents:
5
diff
changeset
|
556 extern C_CIRCULAR_QUEUE_DECLSPEC void* C_CIRCULAR_QUEUE_CALL CircularQueueVoid_ValueAtIndex(CircularQueueVoid* queue, unsigned int the_index); |
0 | 557 |
558 | |
559 | |
560 | |
561 /* Ends C function definitions when using C++ */ | |
562 #ifdef __cplusplus | |
563 } | |
564 #endif | |
565 | |
566 | |
567 | |
568 #endif /* C_CIRCULAR_QUEUE_H */ | |
569 |