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