.Dd July 14, 2024
.Dt QUEUE 9
.Os Camellia
.Sh NAME
.Nm QUEUE_INIT ,
.Nm QUEUE_APPEND ,
.Nm QUEUE_POP
.Nd macros for intrusive linked lists
.Sh SYNOPSIS
.In kernel/queue.h
.Bd -literal
struct YourNode {
	...
	struct YourNode *NAME_next;
};
struct YourHead {
	struct YourNode *head, **slot;
};
.Ed
.Fn QUEUE_INIT "YourHead *q"
.Fn QUEUE_APPEND "YourHead *q" "NAME" "YourNode *el"
.Ft YourNode *
.Fn QUEUE_POP "YourHead *q" "NAME"
.Sh DESCRIPTION
These macros, inspired by BSD's
.In sys/queue.h ,
operate on intrusive linked lists.
Currently, only
.Em queues
\(em singly-linked lists with O(1) insertions at the end \(em
are supported.
.Pp
The linked list internals are intentionally exposed, as they're also meant
to be used by e.g. memory management code for integrity checks.
It's fine to modify them directly.
.Sh RATIONALE
The macros are a bit ugly, but they prevent code duplication,
and using the same implementation everywhere probably makes bugs less likely.
.Pp
I've considered just using
.In sys/queue.h ,
which has the benefit of being more familiar to other programmers,
but I dislike how it hides the list internals from the programmer.