Initial commit

include/bh/queue.h

@@ -0,0 +1,159 @@
+#ifndef BH_QUEUE_H
+#define BH_QUEUE_H
+
+#include <bh/bh.h>
+
+typedef struct bh_queue_s bh_queue_t;
+
+/**
+ * @brief   Create new queue object.
+ *
+ * @return  If the function succeeds, the return value is a pointer to the new
+ *          queue object.
+ * @return  If the function fails, the return value is NULL.
+ *
+ * @sa      bh_queue_free, bh_queue_reserve, bh_queue_insert
+ */
+bh_queue_t *bh_queue_new(void);
+
+/**
+ * @brief   Free queue object.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @sa      bh_queue_clear
+ */
+void bh_queue_free(bh_queue_t *queue);
+
+/**
+ * @brief   Clear the queue.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @warning Clearing the queue does invalidate iterators.
+ *
+ * @sa      bh_queue_remove
+ */
+void bh_queue_clear(bh_queue_t *queue);
+
+/**
+ * @brief   Reserve space for the specified amount of elements.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ * @param   size    The amount of elements.
+ *
+ * @return  If the function succeeds, the return value is zero.
+ * @return  If the function fails, the return value is non-zero.
+ *
+ * @warning Reserving queue space does invalidate iterators.
+ *
+ * @sa      bh_queue_capacity, bh_queue_insert
+ */
+int bh_queue_reserve(bh_queue_t *queue,
+                     size_t size);
+
+/**
+ * @brief   Insert element at the end of the queue.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ * @param   value   Element.
+ *
+ * @return  If the function succeeds, the return value is zero.
+ * @return  If the function fails, the return value is non-zero.
+ *
+ * @warning Inserted element is owned by the caller of the function.
+ * @warning Inserting elements into the queue does invalidate iterators.
+ *
+ * @sa      bh_queue_remove, bh_queue_front
+ */
+int bh_queue_insert(bh_queue_t *queue,
+                    void *value);
+
+/**
+ * @brief   Remove element from the front of the queue.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @warning Removing elements from the queue does invalidate iterators.
+ *
+ * @sa      bh_queue_insert, bh_queue_front
+ */
+void bh_queue_remove(bh_queue_t *queue);
+
+/**
+ * @brief   Return element from the front of the queue.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @return  If the function succeeds, the return value is a valid pointer to
+ *          the element.
+ * @return  If the function fails, the return value is NULL.
+ *
+ * @note    If the queue is empty, function will fail to return element from
+ *          the queue.
+ *
+ * @sa      bh_queue_empty, bh_queue_insert
+ */
+void *bh_queue_front(bh_queue_t *queue);
+
+/**
+ * @brief   Check if the queue is empty.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @return  The return value is non-zero if the queue is empty, otherwise zero.
+ *
+ * @sa      bh_queue_size
+ */
+int bh_queue_empty(bh_queue_t *queue);
+
+/**
+ * @brief   Return queue size.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @return  The return value is current queue size.
+ *
+ * @sa      bh_queue_empty, bh_queue_capacity
+ */
+size_t bh_queue_size(bh_queue_t *queue);
+
+/**
+ * @brief   Return queue capacity.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ *
+ * @return  The return value is current queue capacity.
+ *
+ * @sa      bh_queue_reserve, bh_queue_size
+ */
+size_t bh_queue_capacity(bh_queue_t *queue);
+
+/**
+ * @brief   Return iterator for the next element in the queue.
+ *
+ * @param   queue   Valid pointer to the queue object.
+ * @param   iter    Valid or NULL iterator.
+ *
+ * @return  The return value is the valid iterator for the next element in the
+ *          queue.
+ * @return  The return value is the NULL iterator if there is no more elements
+ *          in the queue.
+ *
+ * @sa      bh_queue_iter_value
+ */
+void *bh_queue_iter_next(bh_queue_t *queue,
+                         void *iter);
+
+/**
+ * @brief   Return pointer to the element's value.
+ *
+ * @param   iter    Valid iterator.
+ *
+ * @return  The return value is the stored element.
+ *
+ * @sa      bh_queue_iter_next
+ */
+void *bh_queue_iter_value(void *iter);
+
+#endif /* BH_QUEUE_H */