sched/wait: Standardize wait_bit_queue naming
authorIngo Molnar <mingo@kernel.org>
Sun, 5 Mar 2017 10:35:27 +0000 (11:35 +0100)
committerIngo Molnar <mingo@kernel.org>
Tue, 20 Jun 2017 10:18:29 +0000 (12:18 +0200)
commit76c85ddc4695bb7b8209bfeff11f5156088f9197
treebd6772616e1c304097cd6d11f3654bc01c4a9127
parent2141713616c652aeabf2dd5c1e89bc601c4fed6a
sched/wait: Standardize wait_bit_queue naming

So wait-bit-queue head variables are often named:

struct wait_bit_queue *q

... which is a bit ambiguous and super confusing, because
they clearly suggest wait-queue head semantics and behavior
(they rhyme with the old wait_queue_t *q naming), while they
are extended wait-queue _entries_, not heads!

They are misnomers in two ways:

 - the 'wait_bit_queue' leaves open the question of whether
   it's an entry or a head

 - the 'q' parameter and local variable naming falsely implies
   that it's a 'queue' - while it's an entry.

This resulted in sometimes confusing cases such as:

finish_wait(wq, &q->wait);

where the 'q' is not a wait-queue head, but a wait-bit-queue entry.

So improve this all by standardizing wait-bit-queue nomenclature
similar to wait-queue head naming:

struct wait_bit_queue   => struct wait_bit_queue_entry
q => wbq_entry

Which makes it all a much clearer:

struct wait_bit_queue_entry *wbq_entry

... and turns the former confusing piece of code into:

finish_wait(wq_head, &wbq_entry->wq_entry;

which IMHO makes it apparently clear what we are doing,
without having to analyze the context of the code: we are
adding a wait-queue entry to a regular wait-queue head,
which entry is embedded in a wait-bit-queue entry.

I'm not a big fan of acronyms, but repeating wait_bit_queue_entry
in field and local variable names is too long, so Hopefully it's
clear enough that 'wq_' prefixes stand for wait-queues, while
'wbq_' prefixes stand for wait-bit-queues.

Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Ingo Molnar <mingo@kernel.org>
include/linux/wait.h
kernel/sched/wait.c