Line data    Source code

       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/swait.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             :  */
      26             : struct completion {
      27             :         unsigned int done;
      28             :         struct swait_queue_head wait;
      29             : };
      30             : 
      31             : #define init_completion_map(x, m) init_completion(x)
      32             : static inline void complete_acquire(struct completion *x) {}
      33             : static inline void complete_release(struct completion *x) {}
      34             : 
      35             : #define COMPLETION_INITIALIZER(work) \
      36             :         { 0, __SWAIT_QUEUE_HEAD_INITIALIZER((work).wait) }
      37             : 
      38             : #define COMPLETION_INITIALIZER_ONSTACK_MAP(work, map) \
      39             :         (*({ init_completion_map(&(work), &(map)); &(work); }))
      40             : 
      41             : #define COMPLETION_INITIALIZER_ONSTACK(work) \
      42             :         (*({ init_completion(&work); &work; }))
      43             : 
      44             : /**
      45             :  * DECLARE_COMPLETION - declare and initialize a completion structure
      46             :  * @work:  identifier for the completion structure
      47             :  *
      48             :  * This macro declares and initializes a completion structure. Generally used
      49             :  * for static declarations. You should use the _ONSTACK variant for automatic
      50             :  * variables.
      51             :  */
      52             : #define DECLARE_COMPLETION(work) \
      53             :         struct completion work = COMPLETION_INITIALIZER(work)
      54             : 
      55             : /*
      56             :  * Lockdep needs to run a non-constant initializer for on-stack
      57             :  * completions - so we use the _ONSTACK() variant for those that
      58             :  * are on the kernel stack:
      59             :  */
      60             : /**
      61             :  * DECLARE_COMPLETION_ONSTACK - declare and initialize a completion structure
      62             :  * @work:  identifier for the completion structure
      63             :  *
      64             :  * This macro declares and initializes a completion structure on the kernel
      65             :  * stack.
      66             :  */
      67             : #ifdef CONFIG_LOCKDEP
      68             : # define DECLARE_COMPLETION_ONSTACK(work) \
      69             :         struct completion work = COMPLETION_INITIALIZER_ONSTACK(work)
      70             : # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) \
      71             :         struct completion work = COMPLETION_INITIALIZER_ONSTACK_MAP(work, map)
      72             : #else
      73             : # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
      74             : # define DECLARE_COMPLETION_ONSTACK_MAP(work, map) DECLARE_COMPLETION(work)
      75             : #endif
      76             : 
      77             : /**
      78             :  * init_completion - Initialize a dynamically allocated completion
      79             :  * @x:  pointer to completion structure that is to be initialized
      80             :  *
      81             :  * This inline function will initialize a dynamically created completion
      82             :  * structure.
      83             :  */
      84             : static inline void init_completion(struct completion *x)
      85             : {
      86         897 :         x->done = 0;
      87         897 :         init_swait_queue_head(&x->wait);
      88             : }
      89             : 
      90             : /**
      91             :  * reinit_completion - reinitialize a completion structure
      92             :  * @x:  pointer to completion structure that is to be reinitialized
      93             :  *
      94             :  * This inline function should be used to reinitialize a completion structure so it can
      95             :  * be reused. This is especially important after complete_all() is used.
      96             :  */
      97             : static inline void reinit_completion(struct completion *x)
      98             : {
      99           0 :         x->done = 0;
     100             : }
     101             : 
     102             : extern void wait_for_completion(struct completion *);
     103             : extern void wait_for_completion_io(struct completion *);
     104             : extern int wait_for_completion_interruptible(struct completion *x);
     105             : extern int wait_for_completion_killable(struct completion *x);
     106             : extern int wait_for_completion_state(struct completion *x, unsigned int state);
     107             : extern unsigned long wait_for_completion_timeout(struct completion *x,
     108             :                                                    unsigned long timeout);
     109             : extern unsigned long wait_for_completion_io_timeout(struct completion *x,
     110             :                                                     unsigned long timeout);
     111             : extern long wait_for_completion_interruptible_timeout(
     112             :         struct completion *x, unsigned long timeout);
     113             : extern long wait_for_completion_killable_timeout(
     114             :         struct completion *x, unsigned long timeout);
     115             : extern bool try_wait_for_completion(struct completion *x);
     116             : extern bool completion_done(struct completion *x);
     117             : 
     118             : extern void complete(struct completion *);
     119             : extern void complete_all(struct completion *);
     120             : 
     121             : #endif