Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> --- man3/circleq.3 | 137 +++++++++++++++++++++++++++++++++++++++++++++++++ man3/queue.3 | 137 ------------------------------------------------- 2 files changed, 137 insertions(+), 137 deletions(-) diff --git a/man3/circleq.3 b/man3/circleq.3 index df547fca7..a28a82919 100644 --- a/man3/circleq.3 +++ b/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 diff --git a/man3/queue.3 b/man3/queue.3 index 247bfb874..794790881 100644 --- a/man3/queue.3 +++ b/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 -- 2.28.0
