diff options
Diffstat (limited to 'src/queue.c')
| -rw-r--r-- | src/queue.c | 135 |
1 files changed, 129 insertions, 6 deletions
diff --git a/src/queue.c b/src/queue.c index 8d48401..e991769 100644 --- a/src/queue.c +++ b/src/queue.c @@ -2,6 +2,19 @@ #include <stdlib.h> #include <string.h> +/** + * \defgroup queue Queue + * + * Data stucture for storing pointers in queue. + * \{ + */ + +/** + * Creates the new queue object. + * + * \return On success, returns the pointer to the new queue object. + * \return On failure, returns a null pointer. + */ bh_queue_t *bh_queue_new(void) { bh_queue_t *result; @@ -13,23 +26,47 @@ bh_queue_t *bh_queue_new(void) return result; } +/** + * Frees the \a queue object. + * + * \param queue Pointer to the queue object to be freed + */ void bh_queue_free(bh_queue_t *queue) { bh_queue_destroy(queue); free(queue); } +/** + * Initializes the \a queue object. + * + * \warning This is an internal function. + * + * \param queue Pointer to the queue object to be initialized + */ void bh_queue_init(bh_queue_t *queue) { memset(queue, 0, sizeof(*queue)); } +/** + * Destroys the \a queue object. + * + * \warning This is an internal function. + * + * \param queue Pointer to the queue object to be destroyed + */ void bh_queue_destroy(bh_queue_t *queue) { if (queue->capacity) free(queue->data); } +/** + * Clears the \a queue object. + * + * \param queue Pointer to the queue object to be cleared + */ void bh_queue_clear(bh_queue_t *queue) { queue->head = 0; @@ -37,6 +74,20 @@ void bh_queue_clear(bh_queue_t *queue) queue->size = 0; } +/** + * Reserves the space for \a size elements in the \a queue. + * + * This function can both expand and shrink the available space in \a queue. + * + * \param queue Pointer to the queue object to be resized in terms of capacity + * \param size New capacity of the queue + * + * \note Calling this function will invalidate iterators. + * \note Actual hashmap capacity can be bigger then requested. + * + * \return On success, returns zero value. + * \return On failure, returns error code. + */ int bh_queue_reserve(bh_queue_t *queue, size_t size) { @@ -48,11 +99,11 @@ int bh_queue_reserve(bh_queue_t *queue, /* New capacity should not exceed maximum capacity */ if (size > ((size_t)-1) / sizeof(void *)) - return -1; + return BH_OOM; /* Prevent same size memory reallocation */ if (size == queue->capacity) - return 0; + return BH_OK; /* Prepare new empty queue */ bh_queue_init(&other); @@ -64,7 +115,7 @@ int bh_queue_reserve(bh_queue_t *queue, other.data = malloc(size * sizeof(void *)); other.capacity = size; if (!other.data) - return -1; + return BH_OOM; /* Iterate over old queue and insert data into new queue */ iter = bh_queue_iter_next(queue, NULL); @@ -81,9 +132,20 @@ int bh_queue_reserve(bh_queue_t *queue, /* Copy queue information */ *queue = other; - return 0; + return BH_OK; } +/** + * Inserts the \a value into the \a queue. + * + * \param queue Pointer to the queue object + * \param value Value to be inserted + * + * \note Calling this function will invalidate iterators. + * + * \return On success, returns zero value. + * \return On failure, returns error code. + */ int bh_queue_insert(bh_queue_t *queue, void *value) { @@ -95,7 +157,7 @@ int bh_queue_insert(bh_queue_t *queue, /* Check potential size overflow and reserve capacity */ capacity = (queue->capacity) ? (queue->capacity * 2) : (16); if (capacity < queue->capacity || bh_queue_reserve(queue, capacity)) - return -1; + return BH_OOM; } /* Increase queue size and advance tail index */ @@ -104,9 +166,16 @@ int bh_queue_insert(bh_queue_t *queue, if (++queue->tail >= queue->capacity) queue->tail = 0; - return 0; + return BH_OK; } +/** + * Removes front value from the \a queue. + * + * \param queue Pointer to the queue object + * + * \note Calling this function will invalidate iterators. + */ void bh_queue_remove(bh_queue_t *queue) { /* Do nothing if queue is empty */ @@ -119,6 +188,14 @@ void bh_queue_remove(bh_queue_t *queue) queue->head = 0; } +/** + * Returns front value from the \a queue. + * + * \param queue Pointer to the queue object + * + * \return On success, returns front value from the queue. + * \return On failure, returns null pointer. + */ void *bh_queue_front(bh_queue_t *queue) { /* Do nothing if queue is empty */ @@ -129,21 +206,56 @@ void *bh_queue_front(bh_queue_t *queue) return queue->data[queue->head]; } +/** + * Checks if the \a queue is empty. + * + * \param queue Pointer to the queue object + * + * \return If queue is empty, returns non-zero value + * \return If queue is not empty, returns zero value + */ int bh_queue_empty(bh_queue_t *queue) { return !queue->size; } +/** + * Returns the size of the \a queue. + * + * \param queue Pointer to the queue object + * + * \return Returns the size of the queue. + */ size_t bh_queue_size(bh_queue_t *queue) { return queue->size; } +/** + * Returns the capacity of the \a queue. + * + * \param queue Pointer to the queue object + * + * \return Returns the capacity of the queue. + */ size_t bh_queue_capacity(bh_queue_t *queue) { return queue->capacity; } +/** + * Returns the iterator to the next element in the \a queue. + * + * \param queue Pointer to the queue object + * \param iter Opaque iterator value + * + * \return If the \a iter doesn't point to the last element of the queue, + * returns next iterator value. + * \return If the \a iter point to the last element of the queue, returns + * null pointer. + * \return If the \a iter is the null pointer, returns iterator to the + * first element of the queue. + */ void *bh_queue_iter_next(bh_queue_t *queue, void *iter) { @@ -170,7 +282,18 @@ void *bh_queue_iter_next(bh_queue_t *queue, return element; } +/** + * Returns the value, pointed by the queue iterator \a iter. + * + * \param iter Opaque iterator value + * + * \return Returns value, pointed by iterator. + */ void *bh_queue_iter_value(void *iter) { return *(void **)iter; } + +/** + * \} + */ |