deps/libretro-common/include/queues/generic_queue.h

   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