Queue

FIFO queue of void *. Use the queue functions to maintain its ordering.

Usage#

Create and initialize a Queue. Pass NULL for stack allocated payloads, or a destructor such as free for payloads the queue should free when destroyed.

Queue queue;
queue_init(&queue, NULL);
int value = 42;
if (queue_enqueue(&queue, &value) == 0) {
    void *data;
    if (queue_dequeue(&queue, &data) == 0) {
        /* data points to value. */
    }
}
queue_destroy(&queue);

Removal returns the payload without calling the destructor. Destroy frees the remaining nodes and runs the destructor on their payloads. It does not free the Queue handle.

Structs#

Queue#

typedef struct {
    List impl;
} Queue;

Enqueue adds at the back. Dequeue and peek read the front.

Functions#

queue_init#

Initializes an empty queue. You own the Queue handle. destroy is an optional deallocation function for payloads remaining at destruction; pass NULL for borrowed data.

void queue_init(Queue *queue, void (*destroy)(void *data));

/* Usage */
Queue *queue = malloc(sizeof(Queue));

// Pass NULL for stack-allocated memory
queue_init(queue, NULL);

// Pass free or a custom freeing function for heap allocated memory
queue_init(queue, free);

queue_destroy#

Destroys the nodes inside a Queue and calls the deallocation function on the data if one was provided. Does not destroy the queue itself, that is left up to the user.

void queue_destroy(Queue *queue);

queue_enqueue#

Adds an element to the back of the queue. Returns 0 on success, -1 on error.

int queue_enqueue(Queue *queue, const void *data);

/* Usage */
int a = 1;
queue_enqueue(queue, &a);

queue_dequeue#

Removes the element at the front of the queue and stores its data in data. Returns 0 on success, -1 if the queue is empty or data is NULL. The destructor is not called. A NULL output does not remove the item.

int queue_dequeue(Queue *queue, void **data);

/* Usage */
// queue: 1 2 3
void *data;
queue_dequeue(queue, &data);
int *t = data;
assert(*t == 1);
// queue: 2 3

queue_peek#

Returns a void * to the front element of the queue without removing it. Returns NULL if the queue is empty or the stored payload is NULL.

void *queue_peek(Queue *queue);

/* Usage */
// queue: 1 2 3
int *t = (int *)queue_peek(queue);
assert(*t == 1);
// queue: 1 2 3

Macros#

queue_size#

Returns the number of elements in the queue.

#define queue_size(q) ((q)->impl.size)

queue_is_empty#

Returns true if the queue has no elements.

#define queue_is_empty(q) ((q)->impl.size == 0)