Queue API

Libmodule offers an easy to use queue implementation, provided by <module/queue.h> header.

Structures

typedef enum {
    QUEUE_WRONG_PARAM = -4,
    QUEUE_MISSING,
    QUEUE_ERR,
    QUEUE_OMEM,
    QUEUE_OK
} queue_ret_code;

/* Callback for queue_iterate */
typedef queue_ret_code (*queue_cb)(void *, void *);

/* Fn for queue_set_dtor */
typedef void (*queue_dtor)(void *);

/* Incomplete struct declaration for queue */
typedef struct _queue queue_t;

/* Incomplete struct declaration for queue iterator */
typedef struct _queue_itr queue_itr_t;

API

Where not specified, these functions return a queue_ret_code.

queue_new(fn)

Create a new queue_t object.

Parameters:

• fn (const queue_dtor) – callback called on value destroy. If NULL, values won’t be automatically destroyed.

Returns:

pointer to newly allocated queue_t.

queue_itr_new(q)

Create a new queue_itr_t object. Note that it can be freed with free().

Parameters:

• s (const queue_t *) – pointer to queue_t

Returns:

pointer to newly allocated queue_itr_t.

queue_itr_next(itr)

Get next iterator. If next iterator is past last element, iterator will be automatically freed.

Parameters:

• itr (queue_itr_t *) – pointer to queue_itr_t

Returns:

pointer to next iterator.

queue_itr_get_data(itr)

Get iterator’s data.

Parameters:

• itr (const queue_itr_t *) – pointer to queue_itr_t

Returns:

pointer to current iterator’s data.

queue_itr_set_data(itr)

Set iterator’s data.

Parameters:

• itr (const queue_itr_t *) – pointer to queue_itr_t

queue_iterate(q, fn, userptr)

Iterate a queue calling cb on each element until QUEUE_OK is returned (or end of queue is reached). Returns QUEUE_MISSING if queue is NULL or empty.
If fn() returns a value != QUEUE_OK, iteration will stop and: if value < QUEUE_OK, value will be returned, else QUEUE_OK will be returned.

Parameters:

• s (queue_t *) – pointer to queue_t
• fn (const queue_cb) – callback to be called
• userptr (void *) – userdata to be passed to callback as first parameter

queue_enqueue(q, val)

Push a value on top of queue.

Parameters:

• s (queue_t *) – pointer to queue_t
• val (void *) – value to be put inside queue

queue_dequeue(q)

Pop a value from top of queue, removing it from queue.

Parameters:

• s (queue_t *) – pointer to queue_t

Returns:

void pointer to value, on NULL on error.

queue_peek(q)

Return queue’s head element, without removing it.

Parameters:

• s (queue_t *) – pointer to queue_t

Returns:

void pointer to value, on NULL on error.

queue_clear(q)

Clears a queue object by deleting any object inside queue.

Parameters:

• s (queue_t *) – pointer to queue_t

queue_free(q)

Free a queue object (it internally calls queue_clear too).

Parameters:

• s (queue_t *) – pointer to queue_t

queue_length(q)

Get queue length.

Parameters:

• s (queue_t *) – pointer to queue_t

Returns:

queue length or a queue_ret_code if any error happens (queue_t is null).