From patchwork Fri Oct 23 14:57:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 40832 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id A6D6F398B410; Fri, 23 Oct 2020 14:58:36 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org A6D6F398B410 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1603465116; bh=4mcoTqiJMog/+48zoQUJEieKUcJ7iX0lzFl2WZbBeZ8=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=KivLc0R83sOTMcefD+fb2yAvriWqJ7RtMRSzS+7+QJGrL0WmbXqCfdxLeZ+F4cfbx OCsjswLbsZhaFZYOwohSXkXHxtxxTyu2c2B6ZRGs88kuxhmm0EIHwLfceCN3hsy53A jskBuD24NvavXfDw/xubDfvlFtmotAtCXdWS5gHQ= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by sourceware.org (Postfix) with ESMTPS id 6B56F3985425 for ; Fri, 23 Oct 2020 14:58:33 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 6B56F3985425 Received: by mail-wr1-x42f.google.com with SMTP id j7so2204657wrt.9 for ; Fri, 23 Oct 2020 07:58:33 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=4mcoTqiJMog/+48zoQUJEieKUcJ7iX0lzFl2WZbBeZ8=; b=Smso0w2UZlFVphGTeeZCYpkd6CMoedfo4vqVEsya6IRd6l9PDk7S7RgfSchZX9zRVp PRxxSlyZ3OGv9KCFw4SneFIHhcwrt8/W9A0iHomhOXlZlg4mWsC97xEEWHnJXwDWfspw fAfAXqKXTXkvp03076gkwblXeu3D2VhJtbZnaYPrnVTSt1tn4Di5un7tewifU1lxi4cV 6uhC0IVhkSVP+aWRW3xR3e9SpR+FTdeliLrZMsRq4QjzfHnDERwmOW+waVvfbkChOXw7 XrniFhXl2VnbZQS8uqCrV09llAlr4Vcytod89uPX0tlVg+RGYelBFBrL9kjBFn7+cNB1 Tp6w== X-Gm-Message-State: AOAM5334Rr1bwAf/h+GiO1LZwvqc89Su9CMswAzkB1CCcVO5Z3dtseef 1KpaheEBWwymkfWFhXx9YPA= X-Google-Smtp-Source: ABdhPJySKCrxOCEQQ4Hx15q3R7n5RTcGQftIud7nr1rN5vyWLWaM53UfbX8uhFBqlf0Llsj2FQEDzg== X-Received: by 2002:adf:f4d2:: with SMTP id h18mr2856980wrp.99.1603465112448; Fri, 23 Oct 2020 07:58:32 -0700 (PDT) Received: from localhost.localdomain ([170.253.60.68]) by smtp.googlemail.com with ESMTPSA id m8sm3755268wrw.17.2020.10.23.07.58.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 23 Oct 2020 07:58:31 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 04/11] circleq.3, queue.3: DESCRIPTION: Move circleq specific code from queue.3 to circleq.3 Date: Fri, 23 Oct 2020 16:57:30 +0200 Message-Id: <20201023145736.102750-5-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201023145736.102750-1-colomar.6.4.3@gmail.com> References: <20201023145736.102750-1-colomar.6.4.3@gmail.com> MIME-Version: 1.0 X-Spam-Status: No, score=-11.2 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, KAM_NUMSUBJECT, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, libc-alpha@sourceware.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Signed-off-by: Alejandro Colomar --- 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