#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 */