sys/queue.h

[aavzz]

Hello

Before asking specific questions about sys/queue.h just wanted to know if there exist some standard or a guideline this file is written according to. Seems like a lot of macro queue libs on the internet resemble it quite closely.

thanks for replies

[kostjn]

I`m found info about this list and queue in man 3 queue.

[aavzz]

The manpage is a little bit dated, btw. What I actually need is not info on how it works or what pointer magic is used (my c is good enough), but _why_ it was (re)written this way. This (imho) could have been done because:
1) some standard on such things existed
2) somebody just thought it appropriate

I'd like to document it (both man & handbook) and some background info will be of interest (I'm a historian, you know :)

[Mel_Flynn]

To provide queues that can be used inside structures without the need for dependencies, mainly in kernel - drivers but also network stack use them extensively. Same for sys/tree.h, less used, but still - for the kernel.

HISTORY
The queue functions first appeared in 4.4BSD.

[aavzz]

2 Mel_Flynn

Thanks for sys/tree.h, i'll study that one too.

At a quick glance, though, its history is much clearer (author, dates and its way to FreeBSD). And it does not have that XXX section of sys/queue.h.

Now to sys/queue.h.

There are insque() and remque() defined at the end (under an XXX comment, which states that they are the old way of doing things). Their only user appears to be netipx/spx_usrreq.c.

My bet is that no one is going to tackle the IPX code, so the need for the two will last for as long as the IPX code exists. And the XXX in sys/queue.h will poke in the eye for a long time.

I propose to move the XXX part of sys/queue.h to a private netipx header (e.g. netipx/_queue.h).

Patch will follow, if the idea is considered worthwhile.

[Mel_Flynn]

While implemented for the kernel, it's not #ifdef _KERNEL, and as such can be used in userland. Allthough I don't know any using insqueue/remqueue, it can break userland apps FreeBSD don't know about.

[aavzz]

Well, actually as long as the XXX part of sys/queue.h is concerned, it _IS_ protected from userland by #ifdef _KERNEL.
I guess, that userland applications are supposed to use insque/remque from libc (#include search.h). Some of them use a separate (private) compatibility queue.h already. That is a descent way of handling any future non standards conforming application.

[ed@]

Hi,

there are insque() and remque() defined at the end (under an xxx comment, which states that they are the old way of doing things). Their only user appears to be netipx/spx_usrreq.c.

My bet is that no one is going to tackle the ipx code, so the need for the two will last for as long as the ipx code exists. And the xxx in sys/queue.h will poke in the eye for a long time.

I propose to move the xxx part of sys/queue.h to a private netipx header (e.g. Netipx/_queue.h).

Patch will follow, if the idea is considered worthwhile.

I just fixed this a couple of minutes ago by creating spx_insque()/spx_remque() in spx_usrreq.c and removing these inline functions from sys/queue.h.

http://svn.freebsd.org/viewvc/base?view=revision&revision=191533
http://svn.freebsd.org/viewvc/base?view=revision&revision=191535

Thanks!

[aavzz]

Thanks a lot, ed@

There is one more issue with sys/queue.h: it contains a macro named SLIST_FOREACH_PREVPTR, which is not used anywhere in the source tree, and is not _mentioned_ where it's sister-macros are mentioned (macro table at the beginning of sys/queue.h & manpage), which implies that nobody knows about it => will never use it.

The question is: should it stay or should it go?

[aavzz]

Added some ascii visualisation to queue manpage.
Changed general description of slist-specific functionality a little bit.
Added SLIST_FOREACH_PREVPTR under BUGS.

Well, at least ascii visualisation is useful imho.

Tried to present it though send-pr, but unsuccessfully :(.