Linux Wait Queue and Completion Summary

Completion
==========

struct completion {
    unsigned int done;
    wait_queue_head_t wait;
};


/* Initializer */

#define COMPLETION_INITIALIZER(work) \
    { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait) }

#define COMPLETION_INITIALIZER_ONSTACK(work) \
    ({ init_completion(&work); work; })

static inline void init_completion(struct completion *x)

/* Re-init */

#define INIT_COMPLETION(x)  ((x).done = 0)

/* Declare and initialize */

#define DECLARE_COMPLETION(work)
#define DECLARE_COMPLETION_ONSTACK(work)

/* TBD - Why the defination of DECLARE_COMPLETION_ONSTACK() is different when
lockdep is enabled or disabled ? */

/* Wait for completion variations */

extern void wait_for_completion(struct completion *);
extern void wait_for_completion_io(struct completion *);
extern int wait_for_completion_interruptible(struct completion *x);
extern int wait_for_completion_killable(struct completion *x);
extern unsigned long wait_for_completion_timeout(struct completion *x,
                           unsigned long timeout);
extern unsigned long wait_for_completion_io_timeout(struct completion *x,
                            unsigned long timeout);
extern long wait_for_completion_interruptible_timeout(
    struct completion *x, unsigned long timeout);
extern long wait_for_completion_killable_timeout(
    struct completion *x, unsigned long timeout);
extern bool try_wait_for_completion(struct completion *x);
extern bool completion_done(struct completion *x);

/* Complete variations */

extern void complete(struct completion *);
extern void complete_all(struct completion *);



Wait Queue
==========

There are two types of "wait", exclusive and non-exclusive. It impacts the behavior of wake_up(), wake_up_nr() and similar APIs.
For example, wake_up() wakes up at most one exclusive task, wake_up_nr() wakes up at most @nr tasks.

How to use wait queue?
---------------------------
The task to be waiting shall:
1. Initialize one wait structure.
2. Call the appropriate wait_* API  or Call add_wait_queue_* API and schedule() or Call prepare_to_wait() and finish_wait()

The task wakes up others shall call:
1. The appropriate wake_up_* API.


Structure
-----------

struct __wait_queue {
    unsigned int flags;
#define WQ_FLAG_EXCLUSIVE   0x01
    void *private;               /* points to task_struct waiting, generally */
    wait_queue_func_t func;     /* called during wake up process, usually default_wakeup_function() or  autoremove_wake_function() */
    struct list_head task_list;     /* link to other wait_queue_t structure */
};

typedef struct __wait_queue wait_queue_t;

struct __wait_queue_head {
    spinlock_t lock;
    struct list_head task_list;
};

typedef struct __wait_queue_head wait_queue_head_t;


Wait queue head initialize
-----------------------------
#define __WAIT_QUEUE_HEAD_INITIALIZER(name)
#define __WAIT_QUEUE_HEAD_INIT_ONSTACK(name)
#define init_waitqueue_head(q)

#define DECLARE_WAIT_QUEUE_HEAD(name)
#define DECLARE_WAIT_QUEUE_HEAD_ONSTACK(name)


API Group 1 - waitqueue is NOT auto removed from waitqueue_head at wakeup time
----------------------------------------------------------------

/* Initializer - wait_queue_t.func is initialized to default_wakeup_function() */

#define __WAITQUEUE_INITIALIZER(name, tsk)
static inline void init_waitqueue_entry(wait_queue_t *q, struct task_struct *p)

#define DECLARE_WAITQUEUE(name, tsk)

/* Add/remove wait_queue_t to wait_queue_head_t */

extern void add_wait_queue(wait_queue_head_t *q, wait_queue_t *wait);
extern void add_wait_queue_exclusive(wait_queue_head_t *q, wait_queue_t *wait);
extern void remove_wait_queue(wait_queue_head_t *q, wait_queue_t *wait);


API Group 2 - Waitqueues which are removed from the waitqueue_head at wakeup time
----------------------------------------------------------------

/* Initializer -  wait_queue_t.func is initialized to autoremove_wake_function()

#define DEFINE_WAIT_FUNC(name, function)
#define DEFINE_WAIT(name) DEFINE_WAIT_FUNC(name, autoremove_wake_function)
#define init_wait(wait)

void prepare_to_wait(wait_queue_head_t *q, wait_queue_t *wait, int state);
void prepare_to_wait_exclusive(wait_queue_head_t *q, wait_queue_t *wait, int state);
void finish_wait(wait_queue_head_t *q, wait_queue_t *wait);


High Level API
-----------------

/*
* Wake up variations
* *_locked - wait queue head lock is held
* *_interruptible - wake up processes sleeping in interruptible state only
* *_all - wait up all processes sleeping
*/

#define wake_up(x)          __wake_up(x, TASK_NORMAL, 1, NULL)
#define wake_up_nr(x, nr)       __wake_up(x, TASK_NORMAL, nr, NULL)
#define wake_up_all(x)          __wake_up(x, TASK_NORMAL, 0, NULL)
#define wake_up_locked(x)       __wake_up_locked((x), TASK_NORMAL, 1)
#define wake_up_all_locked(x)       __wake_up_locked((x), TASK_NORMAL, 0)

#define wake_up_interruptible(x)    __wake_up(x, TASK_INTERRUPTIBLE, 1, NULL)
#define wake_up_interruptible_nr(x, nr) __wake_up(x, TASK_INTERRUPTIBLE, nr, NULL)
#define wake_up_interruptible_all(x)    __wake_up(x, TASK_INTERRUPTIBLE, 0, NULL)
#define wake_up_interruptible_sync(x)   __wake_up_sync((x), TASK_INTERRUPTIBLE, 1)

/* Wait variations
 * Implemented by APIs like prepare_to_wait()/prepare_to_wait_exclusive()/finish_wait().
 */

#define wait_event(wq, condition)          /* uninterruptable */
#define wait_event_timeout(wq, condition, timeout)
#define wait_event_interruptible(wq, condition)
#define wait_event_interruptible_timeout(wq, condition, timeout)
#define wait_event_hrtimeout(wq, condition, timeout)
#define wait_event_interruptible_hrtimeout(wq, condition, timeout)

#define wait_event_interruptible_exclusive(wq, condition)
#define wait_event_interruptible_locked(wq, condition)
#define wait_event_interruptible_locked_irq(wq, condition)
#define wait_event_interruptible_exclusive_locked(wq, condition)
#define wait_event_interruptible_exclusive_locked_irq(wq, condition)

#define wait_event_killable(wq, condition)

#define wait_event_lock_irq_cmd(wq, condition, lock, cmd)
#define wait_event_lock_irq(wq, condition, lock)
#define wait_event_interruptible_lock_irq_cmd(wq, condition, lock, cmd)
#define wait_event_interruptible_lock_irq(wq, condition, lock)