LXR linux/include/linux/completion.h

   1/* SPDX-License-Identifier: GPL-2.0 */
   2#ifndef __LINUX_COMPLETION_H
   3#define __LINUX_COMPLETION_H
   4
   5/*
   6 * (C) Copyright 2001 Linus Torvalds
   7 *
   8 * Atomic wait-for-completion handler data structures.
   9 * See kernel/sched/completion.c for details.
  10 */
  11
  12#include <linux/wait.h>
  13
  14/*
  15 * struct completion - structure used to maintain state for a "completion"
  16 *
  17 * This is the opaque structure used to maintain the state for a "completion".
  18 * Completions currently use a FIFO to queue threads that have to wait for
  19 * the "completion" event.
  20 *
  21 * See also:  complete(), wait_for_completion() (and friends _timeout,
  22 * _interruptible, _interruptible_timeout, and _killable), init_completion(),
  23 * reinit_completion(), and macros DECLARE_COMPLETION(),
  24 * DECLARE_COMPLETION_ONSTACK().
  25 */
  26struct completion {
  27        unsigned int done;
  28        wait_queue_head_t wait;
  29};
  30
  31#define init_completion_map(x, m) __init_completion(x)
  32#define init_completion(x) __init_completion(x)
  33static inline void complete_acquire(struct completion *x) {}
  34static inline void complete_release(struct completion *x) {}
  35
  36#define COMPLETION_INITIALIZER(work) \
  37        { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait) }
  38
  39#define COMPLETION_INITIALIZER_ONSTACK_MAP(work, map) \
  40        (*({ init_completion_map(&(work), &(map)); &(work); }))
  41
  42#define COMPLETION_INITIALIZER_ONSTACK(work) \
  43        (*({ init_completion(&work); &work; }))
  44
  45/**
  46 * DECLARE_COMPLETION - declare and initialize a completion structure
  47 * @work:  identifier for the completion structure
  48 *
  49 * This macro declares and initializes a completion structure. Generally used
  50 * for static declarations. You should use the _ONSTACK variant for automatic
  51 * variables.
  52 */
  53#define DECLARE_COMPLETION(work) \
  54        struct completion work = COMPLETION_INITIALIZER(work)
  55
  56/*
  57 * Lockdep needs to run a non-constant initializer for on-stack
  58 * completions - so we use the _ONSTACK() variant for those that
  59 * are on the kernel stack:
  60 */
  61/**
  62 * DECLARE_COMPLETION_ONSTACK - declare and initialize a completion structure
  63 * @work:  identifier for the completion structure
  64 *
  65 * This macro declares and initializes a completion structure on the kernel
  66 * stack.
  67 */
  68#ifdef CONFIG_LOCKDEP
  69# define DECLARE_COMPLETION_ONSTACK(work) \
  70        struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)
  71# define DECLARE_COMPLETION_ONSTACK_MAP(work, map) \
  72        struct completion work = COMPLETION_INITIALIZER_ONSTACK_MAP(work, map)
  73#else
  74# define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
  75# define DECLARE_COMPLETION_ONSTACK_MAP(work, map) DECLARE_COMPLETION(work)
  76#endif
  77
  78/**
  79 * init_completion - Initialize a dynamically allocated completion
  80 * @x:  pointer to completion structure that is to be initialized
  81 *
  82 * This inline function will initialize a dynamically created completion
  83 * structure.
  84 */
  85static inline void __init_completion(struct completion *x)
  86{
  87        x->done = 0;
  88        init_waitqueue_head(&x->wait);
  89}
  90
  91/**
  92 * reinit_completion - reinitialize a completion structure
  93 * @x:  pointer to completion structure that is to be reinitialized
  94 *
  95 * This inline function should be used to reinitialize a completion structure so it can
  96 * be reused. This is especially important after complete_all() is used.
  97 */
  98static inline void reinit_completion(struct completion *x)
  99{
 100        x->done = 0;
 101}
 102
 103extern void wait_for_completion(struct completion *);
 104extern void wait_for_completion_io(struct completion *);
 105extern int wait_for_completion_interruptible(struct completion *x);
 106extern int wait_for_completion_killable(struct completion *x);
 107extern unsigned long wait_for_completion_timeout(struct completion *x,
 108                                                   unsigned long timeout);
 109extern unsigned long wait_for_completion_io_timeout(struct completion *x,
 110                                                    unsigned long timeout);
 111extern long wait_for_completion_interruptible_timeout(
 112        struct completion *x, unsigned long timeout);
 113extern long wait_for_completion_killable_timeout(
 114        struct completion *x, unsigned long timeout);
 115extern bool try_wait_for_completion(struct completion *x);
 116extern bool completion_done(struct completion *x);
 117
 118extern void complete(struct completion *);
 119extern void complete_all(struct completion *);
 120
 121#endif
 122