Queues

Three queue implementations for different access patterns: a list-backed FIFO, a callback queue keyed on RFuncCallbackCtx, and a refcounted circular ring buffer with bounded capacity. More...

Files
file	rqueue.h
	FIFO queue (list-backed), callback queue, and bounded ring-buffer queue.

Data Structures
struct	RQueueList
	List-backed FIFO / deque. More...
struct	RCBQueue
	List-backed queue of RFuncCallbackCtx entries. More...

Macros
#define	RQueue   RQueueList
	Alias: RQueue is the list-backed queue type.
#define	R_QUEUE_INIT   R_QUEUE_LIST_INIT
	Static initialiser for an empty RQueue.
#define	r_queue_new   r_queue_list_new
	Allocate a heap-backed empty queue.
#define	r_queue_free   r_queue_list_free
	Free a heap-backed queue, calling notify on each remaining item.
#define	r_queue_init   r_queue_list_init
	Initialise a stack-allocated queue to empty.
#define	r_queue_clear   r_queue_list_clear
	Remove all items from q, calling notify on each.
#define	r_queue_push   r_queue_list_push
	Push item onto the tail; returns the new node.
#define	r_queue_pop   r_queue_list_pop
	Pop the head item; returns the item or NULL when empty.
#define	r_queue_peek   r_queue_list_peek
	Peek at the head item without removing it.
#define	r_queue_remove_link   r_queue_list_remove_link
	Remove an arbitrary node from q.
#define	r_queue_size   r_queue_list_size
	Number of items currently in q.
#define	r_queue_is_empty   r_queue_list_is_empty
	TRUE iff q has no items.

Ring-buffer queue (RQueueRing)
Bounded, refcounted FIFO backed by a power-of-two ring buffer. Insert / remove are O(1) and contend over a single producer / consumer index pair; the capacity is fixed at construction. Use when the queue depth has a known upper bound and allocating per push would dominate the cost.
typedef struct RQueueRing	RQueueRing
	Opaque, refcounted ring-buffer queue.
RQueueRing *	r_queue_ring_new (rsize size)
	Construct a ring queue with capacity size (rounded up to a power of 2).
void	r_queue_ring_clear (RQueueRing *q, RDestroyNotify notify)
	Drop every item, calling notify on each.
rboolean	r_queue_ring_push (RQueueRing *q, rpointer item) R_ATTR_WARN_UNUSED_RESULT
	Push item onto the tail.
rpointer	r_queue_ring_pop (RQueueRing *q)
	Remove and return the head item, or NULL when empty.
rpointer	r_queue_ring_peek (RQueueRing *q)
	Peek at the head item without removing it.
rsize	r_queue_ring_size (RQueueRing *q)
	Number of items currently in q.
rboolean	r_queue_ring_is_empty (RQueueRing *q)
	TRUE iff q has no items.
#define	r_queue_ring_ref   r_ref_ref
	Increment the queue's refcount.
#define	r_queue_ring_unref   r_ref_unref
	Decrement the queue's refcount; frees when it reaches zero.

List-backed queue (RQueueList)
static RQueueList *	r_queue_list_new (void)
	Heap-allocate an empty RQueueList.
static void	r_queue_list_init (RQueueList *q)
	Initialise a stack-allocated RQueueList.
static void	r_queue_list_free (RQueueList *q, RDestroyNotify notify)
	Free a heap-allocated queue, calling notify on each item.
static void	r_queue_list_clear (RQueueList *q, RDestroyNotify notify)
	Drop every item from q, calling notify on each.
static RList *	r_queue_list_push (RQueueList *q, rpointer item)
	Append item to the tail; returns the new list node.
static rpointer	r_queue_list_pop (RQueueList *q)
	Remove and return the head item, or NULL when empty.
static rpointer	r_queue_list_peek (const RQueueList *q)
	Peek at the head item without removing it.
static void	r_queue_list_remove_link (RQueueList *q, RList *link)
	Remove an arbitrary link from q.
#define	R_QUEUE_LIST_INIT   { NULL, NULL, 0 }
	Static initialiser for an empty RQueueList.
#define	r_queue_list_size(q)   (q)->size
	Item count.
#define	r_queue_list_is_empty(q)   ((q)->size == 0)
	TRUE iff q has no items.

Callback queue (RCBQueue)
FIFO of RFuncCallbackCtx entries. Used for deferred-work patterns where a producer enqueues callbacks and a consumer fires them later (event loops, idle dispatch, etc.).
static RCBQueue *	r_cbqueue_new (void)
	Heap-allocate an empty RCBQueue.
static void	r_cbqueue_init (RCBQueue *q)
	Initialise a stack-allocated RCBQueue.
static void	r_cbqueue_free (RCBQueue *q)
	Free a heap-allocated callback queue; runs each callback's destroy notifiers.
static void	r_cbqueue_clear (RCBQueue *q)
	Drop all callbacks, running destroy notifiers.
static RCBList *	r_cbqueue_push (RCBQueue *q, RFunc cb, rpointer data, RDestroyNotify datanotify, rpointer user, RDestroyNotify usernotify)
	Append a callback to the tail; returns the new node.
static RCBList *	r_cbqueue_pop (RCBQueue *q)
	Detach and return the head node; caller is responsible for invoking / freeing.
static RCBList *	r_cbqueue_peek (const RCBQueue *q)
	Peek at the head node.
static void	r_cbqueue_remove_link (RCBQueue *q, RCBList *link)
	Remove an arbitrary link from q.
static rsize	r_cbqueue_call (RCBQueue *q)
	Invoke every callback currently queued; returns the number called.
static rsize	r_cbqueue_call_pop (RCBQueue *q)
	Atomically detach + invoke + drop the queue's callbacks.
static void	r_cbqueue_merge (RCBQueue *dst, RCBQueue *src)
	Concatenate src onto dst; src ends up empty.
#define	r_cbqueue_size(q)   (q)->size
	Number of callbacks currently queued.
#define	r_cbqueue_is_empty(q)   ((q)->size == 0)
	TRUE iff no callbacks are queued.

Detailed Description

Three queue implementations for different access patterns: a list-backed FIFO, a callback queue keyed on RFuncCallbackCtx, and a refcounted circular ring buffer with bounded capacity.

RQueue is a typedef alias for RQueueList - the most common choice when nothing else applies. RCBQueue is the deferred-work counterpart that wraps each entry in an RFuncCallbackCtx so the queue can both store and later invoke the work. RQueueRing is for bounded producer/consumer scenarios where an upper bound on the queue depth is known at construction time.

Function Documentation

r_cbqueue_call_pop()

static rsize r_cbqueue_call_pop ( RCBQueue *  q )

inlinestatic

Atomically detach + invoke + drop the queue's callbacks.

Useful for one-shot dispatch where the queue isn't reused afterwards.

r_queue_ring_push()

rboolean r_queue_ring_push	(	RQueueRing *	q,
		rpointer	item
	)

Push item onto the tail.

Returns

FALSE if the ring is full.