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 #ifdef CONFIG_LOCKDEP_COMPLETIONS 14 #include <linux/lockdep.h> 15 #endif 16 17 /* 18 * struct completion - structure used to maintain state for a "completion" 19 * 20 * This is the opaque structure used to maintain the state for a "completion". 21 * Completions currently use a FIFO to queue threads that have to wait for 22 * the "completion" event. 23 * 24 * See also: complete(), wait_for_completion() (and friends _timeout, 25 * _interruptible, _interruptible_timeout, and _killable), init_completion(), 26 * reinit_completion(), and macros DECLARE_COMPLETION(), 27 * DECLARE_COMPLETION_ONSTACK(). 28 */ 29 struct completion { 30 unsigned int done; 31 wait_queue_head_t wait; 32 #ifdef CONFIG_LOCKDEP_COMPLETIONS 33 struct lockdep_map_cross map; 34 #endif 35 }; 36 37 #ifdef CONFIG_LOCKDEP_COMPLETIONS 38 static inline void complete_acquire(struct completion *x) 39 { 40 lock_acquire_exclusive((struct lockdep_map *)&x->map, 0, 0, NULL, _RET_IP_); 41 } 42 43 static inline void complete_release(struct completion *x) 44 { 45 lock_release((struct lockdep_map *)&x->map, 0, _RET_IP_); 46 } 47 48 static inline void complete_release_commit(struct completion *x) 49 { 50 lock_commit_crosslock((struct lockdep_map *)&x->map); 51 } 52 53 #define init_completion(x) \ 54 do { \ 55 static struct lock_class_key __key; \ 56 lockdep_init_map_crosslock((struct lockdep_map *)&(x)->map, \ 57 "(complete)" #x, \ 58 &__key, 0); \ 59 __init_completion(x); \ 60 } while (0) 61 #else 62 #define init_completion(x) __init_completion(x) 63 static inline void complete_acquire(struct completion *x) {} 64 static inline void complete_release(struct completion *x) {} 65 static inline void complete_release_commit(struct completion *x) {} 66 #endif 67 68 #ifdef CONFIG_LOCKDEP_COMPLETIONS 69 #define COMPLETION_INITIALIZER(work) \ 70 { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait), \ 71 STATIC_CROSS_LOCKDEP_MAP_INIT("(complete)" #work, &(work)) } 72 #else 73 #define COMPLETION_INITIALIZER(work) \ 74 { 0, __WAIT_QUEUE_HEAD_INITIALIZER((work).wait) } 75 #endif 76 77 #define COMPLETION_INITIALIZER_ONSTACK(work) \ 78 (*({ init_completion(&work); &work; })) 79 80 /** 81 * DECLARE_COMPLETION - declare and initialize a completion structure 82 * @work: identifier for the completion structure 83 * 84 * This macro declares and initializes a completion structure. Generally used 85 * for static declarations. You should use the _ONSTACK variant for automatic 86 * variables. 87 */ 88 #define DECLARE_COMPLETION(work) \ 89 struct completion work = COMPLETION_INITIALIZER(work) 90 91 /* 92 * Lockdep needs to run a non-constant initializer for on-stack 93 * completions - so we use the _ONSTACK() variant for those that 94 * are on the kernel stack: 95 */ 96 /** 97 * DECLARE_COMPLETION_ONSTACK - declare and initialize a completion structure 98 * @work: identifier for the completion structure 99 * 100 * This macro declares and initializes a completion structure on the kernel 101 * stack. 102 */ 103 #ifdef CONFIG_LOCKDEP 104 # define DECLARE_COMPLETION_ONSTACK(work) \ 105 struct completion work = COMPLETION_INITIALIZER_ONSTACK(work) 106 #else 107 # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work) 108 #endif 109 110 /** 111 * init_completion - Initialize a dynamically allocated completion 112 * @x: pointer to completion structure that is to be initialized 113 * 114 * This inline function will initialize a dynamically created completion 115 * structure. 116 */ 117 static inline void __init_completion(struct completion *x) 118 { 119 x->done = 0; 120 init_waitqueue_head(&x->wait); 121 } 122 123 /** 124 * reinit_completion - reinitialize a completion structure 125 * @x: pointer to completion structure that is to be reinitialized 126 * 127 * This inline function should be used to reinitialize a completion structure so it can 128 * be reused. This is especially important after complete_all() is used. 129 */ 130 static inline void reinit_completion(struct completion *x) 131 { 132 x->done = 0; 133 } 134 135 extern void wait_for_completion(struct completion *); 136 extern void wait_for_completion_io(struct completion *); 137 extern int wait_for_completion_interruptible(struct completion *x); 138 extern int wait_for_completion_killable(struct completion *x); 139 extern unsigned long wait_for_completion_timeout(struct completion *x, 140 unsigned long timeout); 141 extern unsigned long wait_for_completion_io_timeout(struct completion *x, 142 unsigned long timeout); 143 extern long wait_for_completion_interruptible_timeout( 144 struct completion *x, unsigned long timeout); 145 extern long wait_for_completion_killable_timeout( 146 struct completion *x, unsigned long timeout); 147 extern bool try_wait_for_completion(struct completion *x); 148 extern bool completion_done(struct completion *x); 149 150 extern void complete(struct completion *); 151 extern void complete_all(struct completion *); 152 153 #endif 154