#include <kern/circle_queue.h>
Kernel (KEXT) › kern/ primitives

kern/circle_queue.h Kernel.framework

Circle Queue Management APIs These are similar to the queues from queue.h, but the circle queue head is a single pointer to the first element of the queue.
includes: kern/queue.h, kern/assert.h
13 functions · 11 macros · 2 typedefs · 1 struct

structcircle_queue_head

size 8, align 8
queue_entry_thead

typedefcircle_queue_head_t

typedef struct circle_queue_head circle_queue_head_t;

typedefcircle_queue_t

typedef struct circle_queue_head * circle_queue_t;

functioncircle_queue_empty

static inline bool circle_queue_empty(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Returns true if the circle queue contains no elements, i.e. its head pointer is NULL. Circle queues (circle_queue_head_t) are doubly-linked circular lists whose head is a single pointer to the first element, unlike the two-pointer queue heads of queue.h.

functioncircle_queue_first

static inline queue_entry_t circle_queue_first(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Returns the first element of the circle queue, or NULL if the queue is empty.

functioncircle_queue_last

static inline queue_entry_t circle_queue_last(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Returns the last element of the circle queue, found as the prev link of the first element, or NULL if the queue is empty.

functioncircle_queue_next

static inline queue_entry_t circle_queue_next(circle_queue_t cq, queue_entry_t elt)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Returns the element following elt in the circle queue, or NULL if elt is the last element (its next link points back at the queue head element).

functioncircle_queue_length

static inline size_t circle_queue_length(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Returns the number of elements in the circle queue, counted by walking the queue from first to last. O(n) in the queue length.

functioncircle_enqueue_tail

static inline bool circle_enqueue_tail(circle_queue_t cq, queue_entry_t elt)
returns if the queue became non empty

functioncircle_enqueue_head

static inline bool circle_enqueue_head(circle_queue_t cq, queue_entry_t elt)
returns if the queue became non empty

functioncircle_dequeue

static inline void circle_dequeue(circle_queue_t cq, queue_entry_t elt)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Removes the given element from the circle queue, relinking its neighbors and advancing the queue head if the head element is being removed. Validates the element's linkage when queue validation is configured, and clears the removed element's next/prev pointers.

functioncircle_dequeue_head

static inline queue_entry_t circle_dequeue_head(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Removes and returns the first element of the circle queue, or returns NULL if the queue is empty.

functioncircle_dequeue_tail

static inline queue_entry_t circle_dequeue_tail(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Removes and returns the last element of the circle queue, or returns NULL if the queue is empty.

functioncircle_queue_concat_tail

static inline bool circle_queue_concat_tail(circle_queue_t dq, circle_queue_t sq)
returns if the destination queue became non empty

functioncircle_queue_rotate_head_forward

static inline void circle_queue_rotate_head_forward(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Rotates the circle queue forward by one position: the first element becomes the last. No-op on an empty queue. Only the head pointer moves; no element linkage changes.

functioncircle_queue_rotate_head_backward

static inline void circle_queue_rotate_head_backward(circle_queue_t cq)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/circle_queue.h
Rotates the circle queue backward by one position: the last element becomes the first. No-op on an empty queue. Only the head pointer moves; no element linkage changes.

macrocqe_element

Macro: cqe_element Function: Convert a cirle_queue_entry_t pointer to a queue element pointer. Get a pointer to the user-defined element containing a given cirle_queue_entry_t Header: <type> * cqe_element(cirle_queue_entry_t qe, <type>, field) qe - queue entry to convert <type> - what's in the queue (e.g., struct some_data) <field> - is the chain field in <type> Note: Do not use pointer types for <type>
#define cqe_element(qe, type, field) __container_of(qe, type, field)

macrocqe_foreach

Macro: cqe_foreach Function: Iterate over each queue_entry_t structure. Generates a 'for' loop, setting 'qe' to each queue_entry_t in the queue. Header: cqe_foreach(queue_entry_t qe, queue_t head) qe - iteration variable head - pointer to queue_head_t (head of queue) Note: This should only be used with Method 1 queue iteration (linkage chains)
#define cqe_foreach(qe, head) for (qe = circle_queue_first(head); qe; qe = circle_queue_next(head, qe))

macrocqe_foreach_safe

Macro: cqe_foreach_safe Function: Safely iterate over each queue_entry_t structure. Use this iterator macro if you plan to remove the queue_entry_t, qe, from the queue during the iteration. Header: cqe_foreach_safe(queue_entry_t qe, queue_t head) qe - iteration variable head - pointer to queue_head_t (head of queue) Note: This should only be used with Method 1 queue iteration (linkage chains)
#define cqe_foreach_safe(qe, head) for (queue_entry_t _ne, _qe = circle_queue_first(head);
	     (qe = _qe) && (_ne = circle_queue_next(head, _qe), 1);
	     _qe = _ne)

macrocqe_foreach_element

Macro: cqe_foreach_element Function: Iterate over each _element_ in a queue where each queue_entry_t points to another queue_entry_t, i.e., managed by the [de|en]queue_head/ [de|en]queue_tail / remqueue / etc. function. Header: cqe_foreach_element(<type> *elt, queue_t head, <field>) elt - iteration variable <type> - what's in the queue (e.g., struct some_data) <field> - is the chain field in <type> Note: This should only be used with Method 1 queue iteration (linkage chains)
#define cqe_foreach_element(elt, head, field) for (queue_entry_t _qe = circle_queue_first(head);
	     _qe && (elt = cqe_element(_qe, typeof(*(elt)), field), 1);
	     _qe = circle_queue_next(head, _qe))

macrocqe_foreach_element_safe

Macro: cqe_foreach_element_safe Function: Safely iterate over each _element_ in a queue where each queue_entry_t points to another queue_entry_t, i.e., managed by the [de|en]queue_head/ [de|en]queue_tail / remqueue / etc. function. Use this iterator macro if you plan to remove the element, elt, from the queue during the iteration. Header: cqe_foreach_element_safe(<type> *elt, queue_t head, <field>) elt - iteration variable <type> - what's in the queue (e.g., struct some_data) <field> - is the chain field in <type> Note: This should only be used with Method 1 queue iteration (linkage chains)
#define cqe_foreach_element_safe(elt, head, field) for (queue_entry_t _ne, _qe = circle_queue_first(head);
	     _qe && (elt = cqe_element(_qe, typeof(*(elt)), field),
	     _ne = circle_queue_next(head, _qe), 1);
	     _qe = _ne)

macrocqe_dequeue_head

Dequeue an element from head, or return NULL if the queue is empty
#define cqe_dequeue_head(head, type, field) ({
	queue_entry_t _tmp_entry = circle_dequeue_head((head));
	type *_tmp_element = (type*) NULL;
	if (_tmp_entry != (queue_entry_t) NULL)
	        _tmp_element = cqe_element(_tmp_entry, type, field);
	_tmp_element;
})

macrocqe_dequeue_tail

Dequeue an element from tail, or return NULL if the queue is empty
#define cqe_dequeue_tail(head, type, field) ({
	queue_entry_t _tmp_entry = circle_dequeue_tail((head));
	type *_tmp_element = (type*) NULL;
	if (_tmp_entry != (queue_entry_t) NULL)
	        _tmp_element = cqe_element(_tmp_entry, type, field);
	_tmp_element;
})

macrocqe_queue_first

Peek at the first element, or return NULL if the queue is empty
#define cqe_queue_first(head, type, field) ({
	queue_entry_t _tmp_entry = circle_queue_first((head));
	type *_tmp_element = (type*) NULL;
	if (_tmp_entry != (queue_entry_t) NULL)
	        _tmp_element = cqe_element(_tmp_entry, type, field);
	_tmp_element;
})

macrocqe_queue_next

Peek at the next element, or return NULL if it is last
#define cqe_queue_next(elt, head, type, field) ({
	queue_entry_t _tmp_entry = circle_queue_next((head), (elt));
	type *_tmp_element = (type*) NULL;
	if (_tmp_entry != (queue_entry_t) NULL)
	        _tmp_element = cqe_element(_tmp_entry, type, field);
	_tmp_element;
})

macrocqe_queue_last

Peek at the tail element, or return NULL if the queue is empty
#define cqe_queue_last(head, type, field) ({
	queue_entry_t _tmp_entry = circle_queue_last((head));
	type *_tmp_element = (type*) NULL;
	if (_tmp_entry != (queue_entry_t) NULL)
	        _tmp_element = cqe_element(_tmp_entry, type, field);
	_tmp_element;
})

macrocircle_queue_init

Macro: circle_queue_init Function: Initialize the given circle queue. Header: void circle_queue_init(q) circle_queue_t q; \* MODIFIED *\
#define circle_queue_init(q) MACRO_BEGIN
	(q)->head = NULL;
MACRO_END