Commit | Line | Data |
---|---|---|
3719602c PC |
1 | /* Copyright (C) 2010-2020 The RetroArch team |
2 | * | |
3 | * --------------------------------------------------------------------------------------- | |
4 | * The following license statement only applies to this file (generic_queue.h). | |
5 | * --------------------------------------------------------------------------------------- | |
6 | * | |
7 | * Permission is hereby granted, free of charge, | |
8 | * to any person obtaining a copy of this software and associated documentation files (the "Software"), | |
9 | * to deal in the Software without restriction, including without limitation the rights to | |
10 | * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, | |
11 | * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | |
12 | * | |
13 | * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | |
14 | * | |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, | |
16 | * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
18 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
19 | * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
21 | */ | |
22 | ||
23 | #ifndef __LIBRETRO_SDK_GENERIC_QUEUE_H | |
24 | #define __LIBRETRO_SDK_GENERIC_QUEUE_H | |
25 | ||
26 | #include <retro_common_api.h> | |
27 | ||
28 | #include <boolean.h> | |
29 | #include <stddef.h> | |
30 | ||
31 | RETRO_BEGIN_DECLS | |
32 | ||
33 | /** | |
34 | * Represents a generic queue. Can contain any number of elements. Each element contains | |
35 | * a value of type "void *". Can be used as a FIFO or LIFO queue. | |
36 | */ | |
37 | typedef struct generic_queue generic_queue_t; | |
38 | ||
39 | /** | |
40 | * Represents an iterator for iterating over a queue. | |
41 | */ | |
42 | typedef struct generic_queue_iterator generic_queue_iterator_t; | |
43 | ||
44 | /** | |
45 | * Creates a new queue with no elements. | |
46 | * | |
47 | * @return New queue | |
48 | */ | |
49 | generic_queue_t *generic_queue_new(void); | |
50 | ||
51 | /** | |
52 | * @brief frees the memory used by the queue | |
53 | * | |
54 | * Frees all of the memory used by this queue. The values of all | |
55 | * remaining elements are freed using the "free_value" function. Does | |
56 | * nothing if "queue" is NULL. | |
57 | * | |
58 | * @param queue queue to free | |
59 | * @param free_value function to use to free remaining values | |
60 | */ | |
61 | void generic_queue_free(generic_queue_t *queue, void (*free_value)(void *value)); | |
62 | ||
63 | /** | |
64 | * @brief Push a new value onto the queue | |
65 | * | |
66 | * Pushes a new value onto the end of the queue. Does nothing if "queue" | |
67 | * is NULL. | |
68 | * | |
69 | * @param queue queue to the push the value onto | |
70 | * @param value value to push onto the queue | |
71 | */ | |
72 | void generic_queue_push(generic_queue_t *queue, void *value); | |
73 | ||
74 | /** | |
75 | * @brief Remove the last value from the queue | |
76 | * | |
77 | * Removes the last element from the queue. Does nothing if the queue is | |
78 | * NULL. | |
79 | * | |
80 | * @param queue queue to get the value from | |
81 | * @return value of the last element, NULL if queue is empty or NULL | |
82 | */ | |
83 | void *generic_queue_pop(generic_queue_t *queue); | |
84 | ||
85 | /** | |
86 | * @brief Get the last value from the queue | |
87 | * | |
88 | * Returns the value of the last element in the queue. Returns NULL if the | |
89 | * queue is NULL or empty. | |
90 | * | |
91 | * @param queue queue to get the last value from | |
92 | * @return value of the last element or NULL | |
93 | */ | |
94 | void *generic_queue_peek(generic_queue_t *queue); | |
95 | ||
96 | /** | |
97 | * @brief Get the first value from the queue | |
98 | * | |
99 | * Returns the value of the first element in the queue. Returns NULL if the | |
100 | * queue is NULL or empty. | |
101 | * | |
102 | * @param queue queue to get the first value from | |
103 | * @return value of the first element or NULL | |
104 | */ | |
105 | void *generic_queue_peek_first(generic_queue_t *queue); | |
106 | ||
107 | /** | |
108 | * @brief Push a new value onto the front of the queue | |
109 | * | |
110 | * Pushes a new value onto the front of the queue. Does nothing if "queue" | |
111 | * is NULL. | |
112 | * | |
113 | * @param queue queue to the push the value onto | |
114 | * @param value value to push onto the queue | |
115 | */ | |
116 | void generic_queue_shift(generic_queue_t *queue, void *value); | |
117 | ||
118 | /** | |
119 | * @brief Remove the first value from the queue | |
120 | * | |
121 | * Removes the first element from the queue. Does nothing if the queue is | |
122 | * NULL. | |
123 | * | |
124 | * @param queue queue to get the value from | |
125 | * @return value of the last element, NULL if queue is empty or NULL | |
126 | */ | |
127 | void *generic_queue_unshift(generic_queue_t *queue); | |
128 | ||
129 | /** | |
130 | * @brief Get the size of the queue | |
131 | * | |
132 | * Returns the number of elements in the queue. | |
133 | * | |
134 | * @param queue queue to get the size of | |
135 | * @return number of elements in the queue, 0 if queue is NULL | |
136 | */ | |
137 | size_t generic_queue_length(generic_queue_t *queue); | |
138 | ||
139 | /** | |
140 | * @brief Remove the first element in the queue with the provided value | |
141 | * | |
142 | * Removes the first element with a value matching the provided value. Does | |
143 | * nothing if queue is NULL. | |
144 | * | |
145 | * @param queue queue to remove the element from | |
146 | * @param value value to look for in the queue | |
147 | * @return the value of the element removed, NULL if no element was removed | |
148 | */ | |
149 | void *generic_queue_remove(generic_queue_t *queue, void *value); | |
150 | ||
151 | /** | |
152 | * @brief Get an iterator for the queue | |
153 | * | |
154 | * Returns a new iterator for the queue. Can be either a forward or backward | |
155 | * iterator. | |
156 | * | |
157 | * @param queue queue to iterate over | |
158 | * @param forward true for a forward iterator, false for backwards | |
159 | * @return new iterator for the queue in the specified direction, NULL if | |
160 | * "queue" is NULL | |
161 | */ | |
162 | generic_queue_iterator_t *generic_queue_iterator(generic_queue_t *queue, bool forward); | |
163 | ||
164 | /** | |
165 | * @brief Move to the next element in the queue | |
166 | * | |
167 | * Moves the iterator to the next element in the queue. The direction is | |
168 | * specified when retrieving a new iterator. | |
169 | * | |
170 | * @param iterator iterator for the current element | |
171 | * @return iterator for the next element, NULL if iterator is NULL or "iterator" | |
172 | * is at the last element | |
173 | */ | |
174 | generic_queue_iterator_t *generic_queue_iterator_next(generic_queue_iterator_t *iterator); | |
175 | ||
176 | /** | |
177 | * @brief Get the value of the element for the iterator | |
178 | * | |
179 | * Returns the value of the element that the iterator is at. | |
180 | * | |
181 | * @param iterator iterator for the current element | |
182 | * @return value of the element for the iterator | |
183 | */ | |
184 | void *generic_queue_iterator_value(generic_queue_iterator_t *iterator); | |
185 | ||
186 | /** | |
187 | * @brief Remove the element that the iterator is at | |
188 | * | |
189 | * Removes the element that the iterator is at. The iterator is updated to the | |
190 | * next element. | |
191 | * | |
192 | * @param iterator iterator for the current element | |
193 | * @return updated iterator or NULL if the last element was removed | |
194 | */ | |
195 | generic_queue_iterator_t *generic_queue_iterator_remove(generic_queue_iterator_t *iterator); | |
196 | ||
197 | /** | |
198 | * @brief Release the memory for the iterator | |
199 | * | |
200 | * Frees the memory for the provided iterator. Does nothing if "iterator" is NULL. | |
201 | * | |
202 | * @param iterator iterator to free | |
203 | */ | |
204 | void generic_queue_iterator_free(generic_queue_iterator_t *iterator); | |
205 | ||
206 | RETRO_END_DECLS | |
207 | ||
208 | #endif |