mirror of https://github.com/mkerrisk/man-pages
circleq.3, queue.3: DESCRIPTION: Move circleq specific code from queue.3 to circleq.3
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Alejandro Colomar
Michael Kerrisk
parent
8ad9d90ccf
commit
66bb7b4db4
137
man3/circleq.3
137
man3/circleq.3
|
|
@ -69,6 +69,143 @@
|
|||
.Fn CIRCLEQ_PREV "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME"
|
||||
.SH DESCRIPTION
|
||||
.Ss Circular queues
|
||||
A circular queue is headed by a structure defined by the
|
||||
.Nm CIRCLEQ_HEAD
|
||||
macro.
|
||||
This structure contains a pair of pointers,
|
||||
one to the first element in the circular queue and the other to
|
||||
the last element in the circular queue.
|
||||
The elements are doubly linked so that an arbitrary element can be
|
||||
removed without traversing the circular queue.
|
||||
New elements can be added to the circular queue after an existing element,
|
||||
before an existing element, at the head of the circular queue,
|
||||
or at the end of the circular queue.
|
||||
A
|
||||
.Fa CIRCLEQ_HEAD
|
||||
structure is declared as follows:
|
||||
.Bd -literal -offset indent
|
||||
CIRCLEQ_HEAD(HEADNAME, TYPE) head;
|
||||
.Ed
|
||||
.Pp
|
||||
where
|
||||
.Li HEADNAME
|
||||
is the name of the structure to be defined, and
|
||||
.Li TYPE
|
||||
is the type of the elements to be linked into the circular queue.
|
||||
A pointer to the head of the circular queue can later be declared as:
|
||||
.Bd -literal -offset indent
|
||||
struct HEADNAME *headp;
|
||||
.Ed
|
||||
.Pp
|
||||
(The names
|
||||
.Li head
|
||||
and
|
||||
.Li headp
|
||||
are user selectable.)
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_HEAD_INITIALIZER
|
||||
evaluates to an initializer for the circular queue
|
||||
.Fa head .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_EMPTY
|
||||
evaluates to true if there are no items on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_ENTRY
|
||||
declares a structure that connects the elements in
|
||||
the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FIRST
|
||||
returns the first item on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
in the forward direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Fa var
|
||||
is set to
|
||||
.Fa &head
|
||||
if the loop completes normally, or if there were no elements.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH_REVERSE
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
in the reverse direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INIT
|
||||
initializes the circular queue referenced by
|
||||
.Fa head .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_HEAD
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
at the head of the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_TAIL
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
at the end of the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_AFTER
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
after the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_BEFORE
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
before the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LAST
|
||||
returns the last item on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_NEXT
|
||||
returns the next item on the circular queue, or
|
||||
.Fa &head
|
||||
if this item is the last one.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_PREV
|
||||
returns the previous item on the circular queue, or
|
||||
.Fa &head
|
||||
if this item is the first one.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_NEXT
|
||||
returns the next item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
is the last element on the circular queue, the first element is returned.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_PREV
|
||||
returns the previous item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
is the first element on the circular queue, the last element is returned.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_REMOVE
|
||||
removes the element
|
||||
.Fa elm
|
||||
from the circular queue.
|
||||
.SH RETURN VALUE
|
||||
.SH CONFORMING TO
|
||||
.SH BUGS
|
||||
|
|
|
|||
137
man3/queue.3
137
man3/queue.3
|
|
@ -673,143 +673,6 @@ from the tail queue.
|
|||
.\" .Fa head2 .
|
||||
.Pp
|
||||
See the EXAMPLES section below for an example program using a tail queue.
|
||||
.Ss Circular queues
|
||||
A circular queue is headed by a structure defined by the
|
||||
.Nm CIRCLEQ_HEAD
|
||||
macro.
|
||||
This structure contains a pair of pointers,
|
||||
one to the first element in the circular queue and the other to
|
||||
the last element in the circular queue.
|
||||
The elements are doubly linked so that an arbitrary element can be
|
||||
removed without traversing the circular queue.
|
||||
New elements can be added to the circular queue after an existing element,
|
||||
before an existing element, at the head of the circular queue,
|
||||
or at the end of the circular queue.
|
||||
A
|
||||
.Fa CIRCLEQ_HEAD
|
||||
structure is declared as follows:
|
||||
.Bd -literal -offset indent
|
||||
CIRCLEQ_HEAD(HEADNAME, TYPE) head;
|
||||
.Ed
|
||||
.Pp
|
||||
where
|
||||
.Li HEADNAME
|
||||
is the name of the structure to be defined, and
|
||||
.Li TYPE
|
||||
is the type of the elements to be linked into the circular queue.
|
||||
A pointer to the head of the circular queue can later be declared as:
|
||||
.Bd -literal -offset indent
|
||||
struct HEADNAME *headp;
|
||||
.Ed
|
||||
.Pp
|
||||
(The names
|
||||
.Li head
|
||||
and
|
||||
.Li headp
|
||||
are user selectable.)
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_HEAD_INITIALIZER
|
||||
evaluates to an initializer for the circular queue
|
||||
.Fa head .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_EMPTY
|
||||
evaluates to true if there are no items on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_ENTRY
|
||||
declares a structure that connects the elements in
|
||||
the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FIRST
|
||||
returns the first item on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
in the forward direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Fa var
|
||||
is set to
|
||||
.Fa &head
|
||||
if the loop completes normally, or if there were no elements.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_FOREACH_REVERSE
|
||||
traverses the circular queue referenced by
|
||||
.Fa head
|
||||
in the reverse direction, assigning each element in turn to
|
||||
.Fa var .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INIT
|
||||
initializes the circular queue referenced by
|
||||
.Fa head .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_HEAD
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
at the head of the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_TAIL
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
at the end of the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_AFTER
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
after the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_INSERT_BEFORE
|
||||
inserts the new element
|
||||
.Fa elm
|
||||
before the element
|
||||
.Fa listelm .
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LAST
|
||||
returns the last item on the circular queue.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_NEXT
|
||||
returns the next item on the circular queue, or
|
||||
.Fa &head
|
||||
if this item is the last one.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_PREV
|
||||
returns the previous item on the circular queue, or
|
||||
.Fa &head
|
||||
if this item is the first one.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_NEXT
|
||||
returns the next item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
is the last element on the circular queue, the first element is returned.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_LOOP_PREV
|
||||
returns the previous item on the circular queue.
|
||||
If
|
||||
.Fa elm
|
||||
is the first element on the circular queue, the last element is returned.
|
||||
.Pp
|
||||
The macro
|
||||
.Nm CIRCLEQ_REMOVE
|
||||
removes the element
|
||||
.Fa elm
|
||||
from the circular queue.
|
||||
.Sh EXAMPLES
|
||||
.Ss Singly-linked tail queue example
|
||||
.Bd -literal
|
||||
|
|
|
|||
Loading…
Reference in New Issue