From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x543.google.com (mail-ed1-x543.google.com [IPv6:2a00:1450:4864:20::543]) by sourceware.org (Postfix) with ESMTPS id F299A3857C64 for ; Mon, 24 Aug 2020 10:36:57 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org F299A3857C64 Received: by mail-ed1-x543.google.com with SMTP id b2so7581925edw.5 for ; Mon, 24 Aug 2020 03:36:57 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=WZY7i8rJfN05ZeGbbNgd8DkC0898lPPItVqvisC8dRc=; b=nDDjj2GExsfKLW8DAD92gV+AAuymYIMrdb3rZS4JZfcLalbj83s2G1CYfRM6u/fS4m qOb+0bH7ilkeXpigjqw2n3NI8AxiClQPqD8L+Eb+6ONpq1RMSEzhkzr1bsEYcl8fcaeW LT8ivKQjEEdgVc7G1bHpS3gTnoegvzDzM99S2TC9BcnAMNmObXugWgVJBTITZAYbfMxb AogSN+PdUBdUENH3mL5lIC0RKyye0/zyxAEMbGk0Eq9qd+2BT54B3f2GzOVw+D1kcP7J NV6jvbaAwX4vpTqzb1RNs0ZoI0kArExMB6b2QEsG6+0oZI8X0vLXV14h0Gh7ZDzHYlsw QPZQ== X-Gm-Message-State: AOAM533nFgMA/Ma3hUkaV45Lkr0wqd/SUnsP952xfyKwD39/6PMARS8m Tks3tBbLg6kZ3BVN0NwImxk= X-Google-Smtp-Source: ABdhPJwSiXPfHrL3cTpNZHdWY3oKm7ozWIdtA0kzvDn9icwDtU39hbXVXpzVe8P2NQhQDtt2BNXRoA== X-Received: by 2002:a50:fb15:: with SMTP id d21mr4717704edq.312.1598265417085; Mon, 24 Aug 2020 03:36:57 -0700 (PDT) Received: from localhost.localdomain ([185.238.219.17]) by smtp.gmail.com with ESMTPSA id y4sm574798ejj.30.2020.08.24.03.36.54 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 24 Aug 2020 03:36:56 -0700 (PDT) Subject: Re: [patch] queue.3: Document CIRCLEQ_* macros To: Alejandro Colomar Cc: linux-man@vger.kernel.org, libc-alpha@sourceware.org, mtk.manpages@gmail.com References: <88ac5f72-e35e-3912-4b24-c130d3696d91@gmail.com> From: "Michael Kerrisk (man-pages)" Message-ID: <0303eb93-0b7e-20fa-7318-4431514a677b@gmail.com> Date: Mon, 24 Aug 2020 12:36:52 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.7.0 MIME-Version: 1.0 In-Reply-To: <88ac5f72-e35e-3912-4b24-c130d3696d91@gmail.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, NICE_REPLY_A, RCVD_IN_ABUSEAT, RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_NONE, RCVD_IN_SBL_CSS, 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-List-Received-Date: Mon, 24 Aug 2020 10:36:59 -0000 Hello Alejandro, On 8/21/20 2:59 PM, Alejandro Colomar wrote: > =========== > DESCRIPTION > =========== > > Document ``CIRCLEQ_*`` macros, based on old documentation that was > removed by accident in commit ``c0f21a0``, and improved to match the > rest of the documentation in ``queue.3``. Thanks! > ======= > TESTING > ======= > > I run ``sudo make`` and then visualized the man page with > ``man 3 queue``, and the contents looked good. Modulo a few very minor formatting tweaks, yes, looks good. > _______ > > P.S.:  I noticed that ``git format-patch`` leaves a trailing space at > some places: > The line after ``@@ -1220,6 +1274,192 @@ while (n1 != NULL) {`` > The line just before the git version (``-- ``). > However, none of those lines are additions to the code, so they > shouldn't affect the result. > Is that ok? I don't think it's a problem, but... > I run ``git format-patch -1 HEAD --stdout > ../circleq.patch``. > > P.S. 2:  I attached a copy of the patch just in case that the mailer > adds any trailing spaces or any other weird things.  Please, tell me if > there are any inconsistencies in the patch embedded below so that I can > try to prevent them in the future. The inline patch would not apply. I think your mail client might be to blame. I'm not quite sure of the cause. After checking the problem, perhaps you could test by sending yourself a patch, and seeing if you can apply. However, the attachment worked fine, and I applied. (Nevertheless, I prefer inline patches if you can fix your mailer.) Minor comments below. > ________________________________________________________________________ > > From e8f4a79166042d52de8afdfb8530afc7de4fa977 Mon Sep 17 00:00:00 2001 > From: Alejandro Colomar > Date: Fri, 21 Aug 2020 14:27:36 +0200 > Subject: [PATCH] queue.3: Document CIRCLEQ_* macros > > Signed-off-by: Alejandro Colomar > --- >  man3/queue.3 | 256 +++++++++++++++++++++++++++++++++++++++++++++++++-- >  1 file changed, 248 insertions(+), 8 deletions(-) > > diff --git a/man3/queue.3 b/man3/queue.3 > index 260a5b8a5..7fbb92fcc 100644 > --- a/man3/queue.3 > +++ b/man3/queue.3 > @@ -110,10 +110,28 @@ >  .Nm TAILQ_LAST , >  .Nm TAILQ_NEXT , >  .Nm TAILQ_PREV , > -.Nm TAILQ_REMOVE > -.\" .Nm TAILQ_SWAP > +.Nm TAILQ_REMOVE , > +.\" .Nm TAILQ_SWAP , > +.Nm CIRCLEQ_EMPTY , > +.Nm CIRCLEQ_ENTRY , > +.Nm CIRCLEQ_FIRST , > +.Nm CIRCLEQ_FOREACH , > +.Nm CIRCLEQ_FOREACH_REVERSE , > +.Nm CIRCLEQ_HEAD , > +.Nm CIRCLEQ_HEAD_INITIALIZER , > +.Nm CIRCLEQ_INIT , > +.Nm CIRCLEQ_INSERT_AFTER , > +.Nm CIRCLEQ_INSERT_BEFORE , > +.Nm CIRCLEQ_INSERT_HEAD , > +.Nm CIRCLEQ_INSERT_TAIL , > +.Nm CIRCLEQ_LAST , > +.Nm CIRCLEQ_LOOP_NEXT , > +.Nm CIRCLEQ_LOOP_PREV , > +.Nm CIRCLEQ_NEXT , > +.Nm CIRCLEQ_PREV , > +.Nm CIRCLEQ_REMOVE >  .Nd implementations of singly-linked lists, singly-linked tail queues, > -lists and tail queues > +lists, tail queues, and circular queues >  .Sh SYNOPSIS >  .In sys/queue.h >  .\" > @@ -198,11 +216,30 @@ lists and tail queues >  .Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" >  .Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" >  .\" .Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" > "TAILQ_ENTRY NAME" > +.Fn CIRCLEQ_EMPTY "CIRCLEQ_HEAD *head" > +.Fn CIRCLEQ_ENTRY "TYPE" > +.Fn CIRCLEQ_FIRST "CIRCLEQ_HEAD *head" > +.Fn CIRCLEQ_FOREACH "TYPE *var" "CIRCLEQ_HEAD *head" "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_FOREACH_REVERSE "TYPE *var" "CIRCLEQ_HEAD *head" > "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_HEAD "HEADNAME" "TYPE" > +.Fn CIRCLEQ_HEAD_INITIALIZER "CIRCLEQ_HEAD head" > +.Fn CIRCLEQ_INIT "CIRCLEQ_HEAD *head" > +.Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE > *elm" "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_INSERT_BEFORE "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE > *elm" "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_INSERT_HEAD "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY > NAME" > +.Fn CIRCLEQ_INSERT_TAIL "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY > NAME" > +.Fn CIRCLEQ_LAST "CIRCLEQ_HEAD *head" > +.Fn CIRCLEQ_LOOP_NEXT "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY > NAME" > +.Fn CIRCLEQ_LOOP_PREV "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY > NAME" > +.Fn CIRCLEQ_NEXT "TYPE *elm" "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_PREV "TYPE *elm" "CIRCLEQ_ENTRY NAME" > +.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" >  .\" >  .Sh DESCRIPTION > -These macros define and operate on four types of data structures: > -singly-linked lists, singly-linked tail queues, lists, and tail queues. > -All four structures support the following functionality: > +These macros define and operate on five types of data structures: > +singly-linked lists, singly-linked tail queues, lists, tail queues, and > +circular queues. > +All five structures support the following functionality: >  .Pp >  .Bl -enum -compact -offset indent >  .It > @@ -313,6 +350,21 @@ Each head entry requires two pointers rather than one. >  Code size is about 15% greater and operations run about 20% slower >  than singly-linked lists. >  .El > +.Pp---- Why the "----"? It caused a minor formatting glitch. I removed it. > +Circular queues add the following functionality over the above: I added ".Pp" here. Otherwise, everything is fine. Thanks for the patch! Cheers, Michael