Mercurial > almixer_isolated
annotate CircularQueue.h @ 73:32757e494675
Fixed bug that sets the wrong variable for fading in Pause.
There still seems to be another bug related to fading though based on Johnson Lin's test case. Audio no longer stops and triggers the completion callback, but the volume doesn't seem to go up to max for long fade-ins. Still investigating.
| author | Eric Wing <ewing . public |-at-| gmail . com> |
|---|---|
| date | Fri, 10 Aug 2012 22:53:14 -0700 |
| parents | 398d1cb12448 |
| children |
| 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) |
|
72
398d1cb12448
Bug fix for unbalanced #if/#endif blocks. I think I broke it when removing the dllimport for Windows.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
71
diff
changeset
|
42 #else |
|
398d1cb12448
Bug fix for unbalanced #if/#endif blocks. I think I broke it when removing the dllimport for Windows.
Eric Wing <ewing . public |-at-| gmail . com>
parents:
71
diff
changeset
|
43 #define C_CIRCULAR_QUEUE_DECLSPEC |
|
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
|
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 |