Skip to content
  • Ingo Molnar's avatar
    sched/wait: Standardize wait_bit_queue naming · 76c85ddc
    Ingo Molnar authored
    
    
    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: default avatarIngo Molnar <mingo@kernel.org>
    76c85ddc