queue.7, stailq.3, (simpleq.3): Document SIMPLEQ

queue.7, stailq.3, (simpleq.3): Document SIMPLEQ

[Alejandro Colomar (man-pages)]

Hi Michael,

When I refactored queue.3, I found out that there was no documentation
for SIMPLEQ.  I didn't do anything about it because I've never used it
and didn't understand what it was, and more importantly why.

Now I found out that it only exists because of historical reasons [1],
but it is identical to STAILQ (minus a missing SIMPLEQ equivalent for
STAILQ_CONCAT()).  So I'd add links simpleq.3, SIMPLEQ_*.3 -> STAILQ.3,
and add a paragraph to queue.7 and another one to stailq.3.

What do you think about the following?

Also I don't know if we should encourage one of them.  STAILQ seems to
be more complete.  What would you do about it?

Thanks,

Alex

[1]: <https://gitlab.freedesktop.org/libbsd/libbsd/-/issues/5>

---

$ git diff
diff --git a/man7/queue.7 b/man7/queue.7
index f92887a36..c3facafd0 100644
--- a/man7/queue.7
+++ b/man7/queue.7
@@ -138,6 +138,15 @@ Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
 Present on the BSDs.
 .I <sys/queue.h>
 macros first appeared in 4.4BSD.
+.SH NOTES
+Some BSDs provide SIMPLEQ instead of STAILQ.
+The interfaces are identical, but for historical reasons
+they were named differently on different BSDs.
+STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD.
+For compatibility, glibc provides both sets of macros.
 .SH SEE ALSO
 .BR circleq (3),
 .BR insque (3),

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Alejandro Colomar (man-pages)]

[ CC += glibc ]

On 2/10/21 4:06 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> When I refactored queue.3, I found out that there was no documentation
> for SIMPLEQ.  I didn't do anything about it because I've never used it
> and didn't understand what it was, and more importantly why.
> 
> Now I found out that it only exists because of historical reasons [1],
> but it is identical to STAILQ (minus a missing SIMPLEQ equivalent for
> STAILQ_CONCAT()).  So I'd add links simpleq.3, SIMPLEQ_*.3 -> STAILQ.3,
> and add a paragraph to queue.7 and another one to stailq.3.
> 
> What do you think about the following?
> 
> Also I don't know if we should encourage one of them.  STAILQ seems to
> be more complete.  What would you do about it?

BTW, a suggestion for glibc:  glibc could simplify the code with things like

#define SIMPLEQ_ENTRY(type) STAILQ(type)

It would make it more obvious that they're the same thing.

> 
> Thanks,
> 
> Alex
> 
> [1]: <https://gitlab.freedesktop.org/libbsd/libbsd/-/issues/5>
> 
> ---
> 
> $ git diff
> diff --git a/man7/queue.7 b/man7/queue.7
> index f92887a36..c3facafd0 100644
> --- a/man7/queue.7
> +++ b/man7/queue.7
> @@ -138,6 +138,15 @@ Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
>  Present on the BSDs.
>  .I <sys/queue.h>
>  macros first appeared in 4.4BSD.
> +.SH NOTES
> +Some BSDs provide SIMPLEQ instead of STAILQ.
> +The interfaces are identical, but for historical reasons
> +they were named differently on different BSDs.
> +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD.
> +For compatibility, glibc provides both sets of macros.
>  .SH SEE ALSO
>  .BR circleq (3),
>  .BR insque (3),
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Alejandro Colomar (man-pages)]

On 2/10/21 4:11 PM, Alejandro Colomar (man-pages) wrote:
> [ CC += glibc ]
> 
> On 2/10/21 4:06 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> When I refactored queue.3, I found out that there was no documentation
>> for SIMPLEQ.  I didn't do anything about it because I've never used it
>> and didn't understand what it was, and more importantly why.
>>
>> Now I found out that it only exists because of historical reasons [1],
>> but it is identical to STAILQ (minus a missing SIMPLEQ equivalent for
>> STAILQ_CONCAT()).  So I'd add links simpleq.3, SIMPLEQ_*.3 -> STAILQ.3,
>> and add a paragraph to queue.7 and another one to stailq.3.
>>
>> What do you think about the following?
>>
>> Also I don't know if we should encourage one of them.  STAILQ seems to
>> be more complete.  What would you do about it?
> 
> BTW, a suggestion for glibc:  glibc could simplify the code with things like
> 
> #define SIMPLEQ_ENTRY(type) STAILQ(type)
s/STAILQ/&_ENTRY/
> 
> It would make it more obvious that they're the same thing.
> 
>>
>> Thanks,
>>
>> Alex
>>
>> [1]: <https://gitlab.freedesktop.org/libbsd/libbsd/-/issues/5>
>>
>> ---
>>
>> $ git diff
>> diff --git a/man7/queue.7 b/man7/queue.7
>> index f92887a36..c3facafd0 100644
>> --- a/man7/queue.7
>> +++ b/man7/queue.7
>> @@ -138,6 +138,15 @@ Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
>>  Present on the BSDs.
>>  .I <sys/queue.h>
>>  macros first appeared in 4.4BSD.
>> +.SH NOTES
>> +Some BSDs provide SIMPLEQ instead of STAILQ.
>> +The interfaces are identical, but for historical reasons
>> +they were named differently on different BSDs.
>> +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD.
>> +For compatibility, glibc provides both sets of macros.
>>  .SH SEE ALSO
>>  .BR circleq (3),
>>  .BR insque (3),
>>
> 
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Zack Weinberg]

On Wed, Feb 10, 2021 at 10:13 AM Alejandro Colomar (man-pages) via
Libc-alpha <libc-alpha@sourceware.org> wrote:
> > BTW, a suggestion for glibc:  glibc could simplify the code with things like
> >
> > #define SIMPLEQ_ENTRY(type) STAILQ(type)
> s/STAILQ/&_ENTRY/
> >
> > It would make it more obvious that they're the same thing.

I don't know about anyone else on the glibc team, but I personally
consider the entirety of <sys/queue.h> to be provided only for some
degree of backward compatibility with old applications that were
ported from BSD; new code should not use it.  I'd *like* to formally
deprecate it, but I expect that would cause too much breakage to be
viable.  Anyway, I hope you can understand why I'm not interested in
messing with its contents at all.

(Can we add a statement to the effect that new code should not use
<sys/queue.h> to all of the related manpages, please?)

zw

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Alejandro Colomar (man-pages)]

On 2/10/21 4:38 PM, Zack Weinberg wrote:
> On Wed, Feb 10, 2021 at 10:13 AM Alejandro Colomar (man-pages) via
> Libc-alpha <libc-alpha@sourceware.org> wrote:
>>> BTW, a suggestion for glibc:  glibc could simplify the code with things like
>>>
>>> #define SIMPLEQ_ENTRY(type) STAILQ(type)
>> s/STAILQ/&_ENTRY/
>>>
>>> It would make it more obvious that they're the same thing.
> 
> I don't know about anyone else on the glibc team, but I personally
> consider the entirety of <sys/queue.h> to be provided only for some
> degree of backward compatibility with old applications that were
> ported from BSD; new code should not use it.  I'd *like* to formally
> deprecate it, but I expect that would cause too much breakage to be
> viable.  Anyway, I hope you can understand why I'm not interested in
> messing with its contents at all.
> 
> (Can we add a statement to the effect that new code should not use
> <sys/queue.h> to all of the related manpages, please?)
> 
> zw
> 

Hi Zack,

Would you mind explaining your reasons for the deprecation?  Performance?

What functions/macros should be used instead of the queue.h macros?

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Zack Weinberg]

On Wed, Feb 10, 2021 at 10:53 AM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
> On 2/10/21 4:38 PM, Zack Weinberg wrote:
> >
> > I don't know about anyone else on the glibc team, but I personally
> > consider the entirety of <sys/queue.h> to be provided only for some
> > degree of backward compatibility with old applications that were
> > ported from BSD; new code should not use it.  I'd *like* to formally
> > deprecate it, but I expect that would cause too much breakage to be
> > viable.  Anyway, I hope you can understand why I'm not interested in
> > messing with its contents at all.
> >
> > (Can we add a statement to the effect that new code should not use
> > <sys/queue.h> to all of the related manpages, please?)
>
> Would you mind explaining your reasons for the deprecation?  Performance?

No, portability and reliability.   The contents of <sys/queue.h> are
not consistent among the various operating systems that offer it, and
some versions have outright bugs.

> What functions/macros should be used instead of the queue.h macros?

In C, I think applications are better off implementing these simple
data structures themselves.  In any other language, the standard
library probably has something built-in with a more stable and
probably also more ergonomic API.

zw

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Alejandro Colomar (man-pages)]

Hi Zack,

On 2/10/21 5:05 PM, Zack Weinberg wrote:
> On Wed, Feb 10, 2021 at 10:53 AM Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>> On 2/10/21 4:38 PM, Zack Weinberg wrote:
>>>
>>> I don't know about anyone else on the glibc team, but I personally
>>> consider the entirety of <sys/queue.h> to be provided only for some
>>> degree of backward compatibility with old applications that were
>>> ported from BSD; new code should not use it.  I'd *like* to formally
>>> deprecate it, but I expect that would cause too much breakage to be
>>> viable.  Anyway, I hope you can understand why I'm not interested in
>>> messing with its contents at all.
>>>
>>> (Can we add a statement to the effect that new code should not use
>>> <sys/queue.h> to all of the related manpages, please?)
>>
>> Would you mind explaining your reasons for the deprecation?  Performance?
> 
> No, portability and reliability.   The contents of <sys/queue.h> are
> not consistent among the various operating systems that offer it, and
> some versions have outright bugs.

About portability, I guess you are referring to the fact that some
systems don't provide some of the newest macros?  Such as OpenBSD not
providing SIMPLEQ_LAST()?

About bugs, I don't know which, but considering that the BSDs use these
macros, I guess they'll fix whatever new bugs they find.

But for those that offer macros of the same family (with the same name),
I guess they all offer the same interface, don't they?

> 
>> What functions/macros should be used instead of the queue.h macros?
> 
> In C, I think applications are better off implementing these simple
> data structures themselves.  In any other language, the standard
> library probably has something built-in with a more stable and
> probably also more ergonomic API.

If you need to have a high performance linked list, yes, probably it
pays off writing your own.  But for a prototype or some code that isn't
critical, having a libc interface that already provides (somewhat
standard) linked lists is great, IMHO.

Nevertheless, as Michael said back then, if there's consensus in glibc
deprecating these, we could add that to the manual pages.  But as you
said, it's quite difficult to remove those macro sets now, as they have
been used for many years.  However, there's still libbsd providing them
if glibc deprecates them, so it may be possible.

Thanks,

Alex

> 
> zw
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Zack Weinberg]

On Wed, Feb 10, 2021 at 11:24 AM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
> On 2/10/21 5:05 PM, Zack Weinberg wrote:
> > On Wed, Feb 10, 2021 at 10:53 AM Alejandro Colomar (man-pages)
> > <alx.manpages@gmail.com> wrote:
> >> On 2/10/21 4:38 PM, Zack Weinberg wrote:
> >>>
> >>> I don't know about anyone else on the glibc team, but I personally
> >>> consider the entirety of <sys/queue.h> to be provided only for some
> >>> degree of backward compatibility with old applications that were
> >>> ported from BSD; new code should not use it.  I'd *like* to formally
> >>> deprecate it, but I expect that would cause too much breakage to be
> >>> viable.  Anyway, I hope you can understand why I'm not interested in
> >>> messing with its contents at all.
> >>>
> >>> (Can we add a statement to the effect that new code should not use
> >>> <sys/queue.h> to all of the related manpages, please?)
> >>
> >> Would you mind explaining your reasons for the deprecation?  Performance?
> >
> > No, portability and reliability.   The contents of <sys/queue.h> are
> > not consistent among the various operating systems that offer it, and
> > some versions have outright bugs.
>
> About portability, I guess you are referring to the fact that some
> systems don't provide some of the newest macros?  Such as OpenBSD not
> providing SIMPLEQ_LAST()?
>
> But for those that offer macros of the same family (with the same name),
> I guess they all offer the same interface, don't they?

I don't remember specific details anymore -- the troubles I had with
it were going on ten years ago now -- but based on experience
tinkering with user space applications and libraries that tried to use
queue.h, missing macros were unpredictable and varied, and macros with
the same name did *not* reliably provide the same interfaces.

> About bugs, I don't know which, but considering that the BSDs use these
> macros, I guess they'll fix whatever new bugs they find.

The trouble here is that the BSDs' unified source tree means that they
can and do address problems by changing all *their* users to avoid the
bug, rather than fixing the bug in the header.  (This may sound
ridiculous but I've seen it happen dozens of times and not just with
sys/queue.h.)  glibc doesn't have that luxury -- but that means code
developed on Linux becomes unportable by virtue of not having to avoid
bugs that are present on the BSDs.

> If you need to have a high performance linked list, yes, probably it
> pays off writing your own.  But for a prototype or some code that isn't
> critical, having a libc interface that already provides (somewhat
> standard) linked lists is great, IMHO.

Again, it's about correctness, not performance.  I just don't *trust*
sys/queue.h.

zw

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ as an alias of STAILQ

[Michael Kerrisk (man-pages)]

Hello Zack,,On 2/10/21 4:38 PM, Zack Weinberg wrote:
> On Wed, Feb 10, 2021 at 10:13 AM Alejandro Colomar (man-pages) via
> Libc-alpha <libc-alpha@sourceware.org> wrote:
>>> BTW, a suggestion for glibc:  glibc could simplify the code with things like
>>>
>>> #define SIMPLEQ_ENTRY(type) STAILQ(type)
>> s/STAILQ/&_ENTRY/
>>>
>>> It would make it more obvious that they're the same thing.
> 
> I don't know about anyone else on the glibc team, but I personally
> consider the entirety of <sys/queue.h> to be provided only for some
> degree of backward compatibility with old applications that were
> ported from BSD; new code should not use it.  I'd *like* to formally
> deprecate it, but I expect that would cause too much breakage to be
> viable.  Anyway, I hope you can understand why I'm not interested in
> messing with its contents at all.
> 
> (Can we add a statement to the effect that new code should not use
> <sys/queue.h> to all of the related manpages, please?)

I'm not against this, as I think I commented in the past.
But I'd prefer to have some rough consensus about this from
the glibc team before making suchg a change.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: queue.7, stailq.3, (simpleq.3): Document SIMPLEQ

[Michael Kerrisk (man-pages)]

Hi Alex,

On 2/10/21 4:06 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> When I refactored queue.3, I found out that there was no documentation
> for SIMPLEQ.  I didn't do anything about it because I've never used it
> and didn't understand what it was, and more importantly why.
> 
> Now I found out that it only exists because of historical reasons [1],
> but it is identical to STAILQ (minus a missing SIMPLEQ equivalent for
> STAILQ_CONCAT()).  So I'd add links simpleq.3, SIMPLEQ_*.3 -> STAILQ.3,
> and add a paragraph to queue.7 and another one to stailq.3.
> 
> What do you think about the following?

I think the proposed patch is okay. Do you want to send me
a final version?

> 
> Also I don't know if we should encourage one of them.  STAILQ seems to
> be more complete.  What would you do about it?

Not knowing, I would say: let's say nothing for now.

Thanks,

Michael


> [1]: <https://gitlab.freedesktop.org/libbsd/libbsd/-/issues/5>
> 
> ---
> 
> $ git diff
> diff --git a/man7/queue.7 b/man7/queue.7
> index f92887a36..c3facafd0 100644
> --- a/man7/queue.7
> +++ b/man7/queue.7
> @@ -138,6 +138,15 @@ Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008.
>  Present on the BSDs.
>  .I <sys/queue.h>
>  macros first appeared in 4.4BSD.
> +.SH NOTES
> +Some BSDs provide SIMPLEQ instead of STAILQ.
> +The interfaces are identical, but for historical reasons
> +they were named differently on different BSDs.
> +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD.
> +For compatibility, glibc provides both sets of macros.
>  .SH SEE ALSO
>  .BR circleq (3),
>  .BR insque (3),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/