completions - wait for completion handling
  ==========================================
  
  This document was originally written based on 3.18.0 (linux-next)
  
  Introduction:
  -------------
  
  If you have one or more threads of execution that must wait for some process

  to have reached a point or a specific state, completions can provide a
  race-free solution to this problem. Semantically they are somewhat like a
  pthread_barrier and have similar use-cases.

  Completions are a code synchronization mechanism which is preferable to any

  misuse of locks. Any time you think of using yield() or some quirky

  msleep(1) loop to allow something else to proceed, you probably want to

  look into using one of the wait_for_completion*() calls instead. The

  advantage of using completions is clear intent of the code, but also more

  efficient code as both threads can continue until the result is actually
  needed.
  
  Completions are built on top of the generic event infrastructure in Linux,

  with the event reduced to a simple flag (appropriately called "done") in
  struct completion that tells the waiting threads of execution if they

  can continue safely.

  As completions are scheduling related, the code is found in

  kernel/sched/completion.c - for details on completion design and
  implementation see completions-design.txt
  
  
  Usage:
  ------

  There are three parts to using completions, the initialization of the

  struct completion, the waiting part through a call to one of the variants of

  wait_for_completion() and the signaling side through a call to complete()

  or complete_all(). Further there are some helper functions for checking the
  state of completions.
  
  To use completions one needs to include <linux/completion.h> and
  create a variable of type struct completion. The structure used for
  handling of completions is:
  
  	struct completion {
  		unsigned int done;
  		wait_queue_head_t wait;
  	};
  
  providing the wait queue to place tasks on for waiting and the flag for
  indicating the state of affairs.

  Completions should be named to convey the intent of the waiter. A good

  example is:
  
  	wait_for_completion(&early_console_added);
  
  	complete(&early_console_added);
  
  Good naming (as always) helps code readability.
  
  
  Initializing completions:
  -------------------------
  
  Initialization of dynamically allocated completions, often embedded in
  other structures, is done with:
  
  	void init_completion(&done);
  
  Initialization is accomplished by initializing the wait queue and setting
  the default state to "not available", that is, "done" is set to 0.
  
  The re-initialization function, reinit_completion(), simply resets the
  done element to "not available", thus again to 0, without touching the

  wait queue. Calling init_completion() twice on the same completion object is

  most likely a bug as it re-initializes the queue to an empty queue and
  enqueued tasks could get "lost" - use reinit_completion() in that case.
  
  For static declaration and initialization, macros are available. These are:
  
  	static DECLARE_COMPLETION(setup_done)
  
  used for static declarations in file scope. Within functions the static
  initialization should always use:
  
  	DECLARE_COMPLETION_ONSTACK(setup_done)
  
  suitable for automatic/local variables on the stack and will make lockdep

  happy. Note also that one needs to make *sure* the completion passed to

  work threads remains in-scope, and no references remain to on-stack data
  when the initiating function returns.

  Using on-stack completions for code that calls any of the _timeout or
  _interruptible/_killable variants is not advisable as they will require
  additional synchronization to prevent the on-stack completion object in
  the timeout/signal cases from going out of scope. Consider using dynamically
  allocated completions when intending to use the _interruptible/_killable
  or _timeout variants of wait_for_completion().

  
  Waiting for completions:
  ------------------------
  
  For a thread of execution to wait for some concurrent work to finish, it
  calls wait_for_completion() on the initialized completion structure.
  A typical usage scenario is:

  	struct completion setup_done;

  	init_completion(&setup_done);

  	initialize_work(...,&setup_done,...)

  
  	/* run non-dependent code */              /* do setup */

  	wait_for_completion(&setup_done);         complete(setup_done)

  This is not implying any temporal order on wait_for_completion() and the

  call to complete() - if the call to complete() happened before the call
  to wait_for_completion() then the waiting side simply will continue

  immediately as all dependencies are satisfied if not it will block until
  completion is signaled by complete().

  Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(),

  so it can only be called safely when you know that interrupts are enabled.

  Calling it from hard-irq or irqs-off atomic contexts will result in
  hard-to-detect spurious enabling of interrupts.

  
  wait_for_completion():
  
  	void wait_for_completion(struct completion *done):

  The default behavior is to wait without a timeout and to mark the task as

  uninterruptible. wait_for_completion() and its variants are only safe

  in process context (as they can sleep) but not in atomic context,
  interrupt context, with disabled irqs. or preemption is disabled - see also
  try_wait_for_completion() below for handling completion in atomic/interrupt
  context.

  As all variants of wait_for_completion() can (obviously) block for a long

  time, you probably don't want to call this with held mutexes.

  
  
  Variants available:
  -------------------
  
  The below variants all return status and this status should be checked in
  most(/all) cases - in cases where the status is deliberately not checked you
  probably want to make a note explaining this (e.g. see
  arch/arm/kernel/smp.c:__cpu_up()).
  
  A common problem that occurs is to have unclean assignment of return types,
  so care should be taken with assigning return-values to variables of proper
  type. Checking for the specific meaning of return values also has been found
  to be quite inaccurate e.g. constructs like

  if (!wait_for_completion_interruptible_timeout(...)) would execute the same

  code path for successful completion and for the interrupted case - which is
  probably not what you want.
  
  	int wait_for_completion_interruptible(struct completion *done)

  This function marks the task TASK_INTERRUPTIBLE. If a signal was received

  while waiting it will return -ERESTARTSYS; 0 otherwise.

  
  	unsigned long wait_for_completion_timeout(struct completion *done,
  		unsigned long timeout)

  The task is marked as TASK_UNINTERRUPTIBLE and will wait at most 'timeout'
  (in jiffies). If timeout occurs it returns 0 else the remaining time in

  jiffies (but at least 1). Timeouts are preferably calculated with
  msecs_to_jiffies() or usecs_to_jiffies(). If the returned timeout value is
  deliberately ignored a comment should probably explain why (e.g. see
  drivers/mfd/wm8350-core.c wm8350_read_auxadc())

  
  	long wait_for_completion_interruptible_timeout(
  		struct completion *done, unsigned long timeout)

  This function passes a timeout in jiffies and marks the task as
  TASK_INTERRUPTIBLE. If a signal was received it will return -ERESTARTSYS;
  otherwise it returns 0 if the completion timed out or the remaining time in
  jiffies if completion occurred.

  Further variants include _killable which uses TASK_KILLABLE as the
  designated tasks state and will return -ERESTARTSYS if it is interrupted or
  else 0 if completion was achieved.  There is a _timeout variant as well:

  
  	long wait_for_completion_killable(struct completion *done)
  	long wait_for_completion_killable_timeout(struct completion *done,
  		unsigned long timeout)

  The _io variants wait_for_completion_io() behave the same as the non-_io

  variants, except for accounting waiting time as waiting on IO, which has

  an impact on how the task is accounted in scheduling stats.

  
  	void wait_for_completion_io(struct completion *done)
  	unsigned long wait_for_completion_io_timeout(struct completion *done
  		unsigned long timeout)
  
  
  Signaling completions:
  ----------------------

  A thread that wants to signal that the conditions for continuation have been
  achieved calls complete() to signal exactly one of the waiters that it can
  continue.

  
  	void complete(struct completion *done)

  or calls complete_all() to signal all current and future waiters.

  
  	void complete_all(struct completion *done)
  
  The signaling will work as expected even if completions are signaled before
  a thread starts waiting. This is achieved by the waiter "consuming"
  (decrementing) the done element of struct completion. Waiting threads
  wakeup order is the same in which they were enqueued (FIFO order).
  
  If complete() is called multiple times then this will allow for that number
  of waiters to continue - each call to complete() will simply increment the
  done element. Calling complete_all() multiple times is a bug though. Both

  complete() and complete_all() can be called in hard-irq/atomic context safely.

  
  There only can be one thread calling complete() or complete_all() on a

  particular struct completion at any time - serialized through the wait

  queue spinlock. Any such concurrent calls to complete() or complete_all()
  probably are a design bug.
  
  Signaling completion from hard-irq context is fine as it will appropriately

  lock with spin_lock_irqsave/spin_unlock_irqrestore and it will never sleep.

  
  
  try_wait_for_completion()/completion_done():
  --------------------------------------------

  The try_wait_for_completion() function will not put the thread on the wait
  queue but rather returns false if it would need to enqueue (block) the thread,

  else it consumes one posted completion and returns true.

  	bool try_wait_for_completion(struct completion *done)

  Finally, to check the state of a completion without changing it in any way, 
  call completion_done(), which returns false if there are no posted
  completions that were not yet consumed by waiters (implying that there are
  waiters) and true otherwise;

  	bool completion_done(struct completion *done)

  
  Both try_wait_for_completion() and completion_done() are safe to be called in

  hard-irq or atomic context.