160 lines
4.0 KiB
C
160 lines
4.0 KiB
C
#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 */
|