1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (generic_queue.h).
5 * ---------------------------------------------------------------------------------------
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:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
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.
23 #ifndef __LIBRETRO_SDK_GENERIC_QUEUE_H
24 #define __LIBRETRO_SDK_GENERIC_QUEUE_H
26 #include <retro_common_api.h>
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.
37 typedef struct generic_queue generic_queue_t;
40 * Represents an iterator for iterating over a queue.
42 typedef struct generic_queue_iterator generic_queue_iterator_t;
45 * Creates a new queue with no elements.
49 generic_queue_t *generic_queue_new(void);
52 * @brief frees the memory used by the queue
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.
58 * @param queue queue to free
59 * @param free_value function to use to free remaining values
61 void generic_queue_free(generic_queue_t *queue, void (*free_value)(void *value));
64 * @brief Push a new value onto the queue
66 * Pushes a new value onto the end of the queue. Does nothing if "queue"
69 * @param queue queue to the push the value onto
70 * @param value value to push onto the queue
72 void generic_queue_push(generic_queue_t *queue, void *value);
75 * @brief Remove the last value from the queue
77 * Removes the last element from the queue. Does nothing if the queue is
80 * @param queue queue to get the value from
81 * @return value of the last element, NULL if queue is empty or NULL
83 void *generic_queue_pop(generic_queue_t *queue);
86 * @brief Get the last value from the queue
88 * Returns the value of the last element in the queue. Returns NULL if the
89 * queue is NULL or empty.
91 * @param queue queue to get the last value from
92 * @return value of the last element or NULL
94 void *generic_queue_peek(generic_queue_t *queue);
97 * @brief Get the first value from the queue
99 * Returns the value of the first element in the queue. Returns NULL if the
100 * queue is NULL or empty.
102 * @param queue queue to get the first value from
103 * @return value of the first element or NULL
105 void *generic_queue_peek_first(generic_queue_t *queue);
108 * @brief Push a new value onto the front of the queue
110 * Pushes a new value onto the front of the queue. Does nothing if "queue"
113 * @param queue queue to the push the value onto
114 * @param value value to push onto the queue
116 void generic_queue_shift(generic_queue_t *queue, void *value);
119 * @brief Remove the first value from the queue
121 * Removes the first element from the queue. Does nothing if the queue is
124 * @param queue queue to get the value from
125 * @return value of the last element, NULL if queue is empty or NULL
127 void *generic_queue_unshift(generic_queue_t *queue);
130 * @brief Get the size of the queue
132 * Returns the number of elements in the queue.
134 * @param queue queue to get the size of
135 * @return number of elements in the queue, 0 if queue is NULL
137 size_t generic_queue_length(generic_queue_t *queue);
140 * @brief Remove the first element in the queue with the provided value
142 * Removes the first element with a value matching the provided value. Does
143 * nothing if queue is NULL.
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
149 void *generic_queue_remove(generic_queue_t *queue, void *value);
152 * @brief Get an iterator for the queue
154 * Returns a new iterator for the queue. Can be either a forward or backward
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
162 generic_queue_iterator_t *generic_queue_iterator(generic_queue_t *queue, bool forward);
165 * @brief Move to the next element in the queue
167 * Moves the iterator to the next element in the queue. The direction is
168 * specified when retrieving a new iterator.
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
174 generic_queue_iterator_t *generic_queue_iterator_next(generic_queue_iterator_t *iterator);
177 * @brief Get the value of the element for the iterator
179 * Returns the value of the element that the iterator is at.
181 * @param iterator iterator for the current element
182 * @return value of the element for the iterator
184 void *generic_queue_iterator_value(generic_queue_iterator_t *iterator);
187 * @brief Remove the element that the iterator is at
189 * Removes the element that the iterator is at. The iterator is updated to the
192 * @param iterator iterator for the current element
193 * @return updated iterator or NULL if the last element was removed
195 generic_queue_iterator_t *generic_queue_iterator_remove(generic_queue_iterator_t *iterator);
198 * @brief Release the memory for the iterator
200 * Frees the memory for the provided iterator. Does nothing if "iterator" is NULL.
202 * @param iterator iterator to free
204 void generic_queue_iterator_free(generic_queue_iterator_t *iterator);