queue: Add STAILQ_SPLIT_AFTER() and STAILQ_ASSERT_NONEMPTY()

[olce]

Summary

STAILQ_SPLIT_AFTER() allows to split an existing queue in two. It is
the missing block that enables arbitrary splitting and recombinations of
queues, together with STAILQ_CONCAT() and STAILQ_SWAP().

Add STAILQ_ASSERT_NONEMPTY(), used by STAILQ_SPLIT_AFTER().

[markj]

The implementation looks fine to me. queue.3 needs an update as well.

sys/sys/queue.h

483

Does it make sense to add QMD_STAILQ_CHECK_TAIL(head) as well?

[olce]

• STAILQ_SPLIT_AFTER(): Add a call to QMD_STAILQ_CHECK_TAIL().
• STAILQ_SPLIT_AFTER(): Simplify the test determining if elm is the last element of the stailq.
• Expand a bit the commit message.

[olce]

In D49608#1131466, @markj wrote:

The implementation looks fine to me. queue.3 needs an update as well.

Will do that in a later commit. In between, going to submit more changes to queue.h, including the implementation of _SPLIT_AFTER for all lists/tailqs variants.

[emaste]

Will do that in a later commit.

In general updates to man pages, tests, etc. should be included in the commit that adds or changes the functionality.

[olce]

Remove superfluous ; after while (0) in some macros.

[olce]

Please see D49969 and following for consistent changes to other lists/queues, documentation and finer control of check debug code inserted by queue macros.

[markj]

sys/sys/queue.h

377

Why not make these KASSERTs and define them unconditionally? Are they only meant to be used within queue.h?

Prefixing the panic string with the function name would be useful IMO.

[olce]

sys/sys/queue.h

377

These are meant to be used both externally and internally.

I did not turn these into KASSERTs as a revision further in the series replaces the calls to panic() by QMD_PANIC() with the aim to support userland debugging, and also because I intended insertion or elision of the queue debugging code to be independent of the presence of INVARIANTS when desired. Having some userland version of assert() supporting custom messages and variable arguments would encourage using something like QMD_ASSERT() (user-defined, or automatically defined to KASSERT() on kernel build with INVARIANTS) instead of QMD_PANIC().

Function name prefix added. I usually refrain from doing this as a stack trace is normally available on panic (so the function name info is redundant), but that is not the case in userland, e.g., when calling abort().

[markj]

sys/sys/queue.h

377

I usually refrain from doing this as a stack trace is normally available on panic (so the function name info is redundant),

I've had enough issues with incomplete/incorrect backtraces (e.g., stack unwinding from ddb appears to be unreliable on riscv at the moment) and inlined functions that having the function name in the panic string is worth it. Consider also that calling a _Noreturn function can cause the current stack frame to be overwritten and thus omitted from the backtrace.

[olce]

sys/sys/queue.h

377

Oh, OK.