git.sesse.net Git - bcachefs-tools-debian/blob - linux/completion.c

   1 /*
   2  * Generic wait-for-completion handler;
   3  *
   4  * It differs from semaphores in that their default case is the opposite,
   5  * wait_for_completion default blocks whereas semaphore default non-block. The
   6  * interface also makes it easy to 'complete' multiple waiting threads,
   7  * something which isn't entirely natural for semaphores.
   8  *
   9  * But more importantly, the primitive documents the usage. Semaphores would
  10  * typically be used for exclusion which gives rise to priority inversion.
  11  * Waiting for completion is a typically sync point, but not an exclusion point.
  12  */
  13
  14 #include <linux/sched.h>
  15 #include <linux/completion.h>
  16
  17 /**
  18  * complete: - signals a single thread waiting on this completion
  19  * @x:  holds the state of this particular completion
  20  *
  21  * This will wake up a single thread waiting on this completion. Threads will be
  22  * awakened in the same order in which they were queued.
  23  *
  24  * See also complete_all(), wait_for_completion() and related routines.
  25  *
  26  * It may be assumed that this function implies a write memory barrier before
  27  * changing the task state if and only if any tasks are woken up.
  28  */
  29 void complete(struct completion *x)
  30 {
  31         unsigned long flags;
  32
  33         spin_lock_irqsave(&x->wait.lock, flags);
  34         x->done++;
  35         __wake_up_locked(&x->wait, TASK_NORMAL, 1);
  36         spin_unlock_irqrestore(&x->wait.lock, flags);
  37 }
  38 EXPORT_SYMBOL(complete);
  39
  40 /**
  41  * complete_all: - signals all threads waiting on this completion
  42  * @x:  holds the state of this particular completion
  43  *
  44  * This will wake up all threads waiting on this particular completion event.
  45  *
  46  * It may be assumed that this function implies a write memory barrier before
  47  * changing the task state if and only if any tasks are woken up.
  48  */
  49 void complete_all(struct completion *x)
  50 {
  51         unsigned long flags;
  52
  53         spin_lock_irqsave(&x->wait.lock, flags);
  54         x->done += UINT_MAX/2;
  55         __wake_up_locked(&x->wait, TASK_NORMAL, 0);
  56         spin_unlock_irqrestore(&x->wait.lock, flags);
  57 }
  58 EXPORT_SYMBOL(complete_all);
  59
  60 static inline long __sched
  61 do_wait_for_common(struct completion *x,
  62                    long (*action)(long), long timeout, int state)
  63 {
  64         if (!x->done) {
  65                 DECLARE_WAITQUEUE(wait, current);
  66
  67                 __add_wait_queue_tail_exclusive(&x->wait, &wait);
  68                 do {
  69                         __set_current_state(state);
  70                         spin_unlock_irq(&x->wait.lock);
  71                         timeout = action(timeout);
  72                         spin_lock_irq(&x->wait.lock);
  73                 } while (!x->done && timeout);
  74                 __remove_wait_queue(&x->wait, &wait);
  75                 if (!x->done)
  76                         return timeout;
  77         }
  78         x->done--;
  79         return timeout ?: 1;
  80 }
  81
  82 static inline long __sched
  83 __wait_for_common(struct completion *x,
  84                   long (*action)(long), long timeout, int state)
  85 {
  86         might_sleep();
  87
  88         spin_lock_irq(&x->wait.lock);
  89         timeout = do_wait_for_common(x, action, timeout, state);
  90         spin_unlock_irq(&x->wait.lock);
  91         return timeout;
  92 }
  93
  94 static long __sched
  95 wait_for_common(struct completion *x, long timeout, int state)
  96 {
  97         return __wait_for_common(x, schedule_timeout, timeout, state);
  98 }
  99
 100 static long __sched
 101 wait_for_common_io(struct completion *x, long timeout, int state)
 102 {
 103         return __wait_for_common(x, io_schedule_timeout, timeout, state);
 104 }
 105
 106 /**
 107  * wait_for_completion: - waits for completion of a task
 108  * @x:  holds the state of this particular completion
 109  *
 110  * This waits to be signaled for completion of a specific task. It is NOT
 111  * interruptible and there is no timeout.
 112  *
 113  * See also similar routines (i.e. wait_for_completion_timeout()) with timeout
 114  * and interrupt capability. Also see complete().
 115  */
 116 void __sched wait_for_completion(struct completion *x)
 117 {
 118         wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
 119 }
 120 EXPORT_SYMBOL(wait_for_completion);
 121
 122 /**
 123  * wait_for_completion_timeout: - waits for completion of a task (w/timeout)
 124  * @x:  holds the state of this particular completion
 125  * @timeout:  timeout value in jiffies
 126  *
 127  * This waits for either a completion of a specific task to be signaled or for a
 128  * specified timeout to expire. The timeout is in jiffies. It is not
 129  * interruptible.
 130  *
 131  * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
 132  * till timeout) if completed.
 133  */
 134 unsigned long __sched
 135 wait_for_completion_timeout(struct completion *x, unsigned long timeout)
 136 {
 137         return wait_for_common(x, timeout, TASK_UNINTERRUPTIBLE);
 138 }
 139 EXPORT_SYMBOL(wait_for_completion_timeout);
 140
 141 /**
 142  * wait_for_completion_io: - waits for completion of a task
 143  * @x:  holds the state of this particular completion
 144  *
 145  * This waits to be signaled for completion of a specific task. It is NOT
 146  * interruptible and there is no timeout. The caller is accounted as waiting
 147  * for IO (which traditionally means blkio only).
 148  */
 149 void __sched wait_for_completion_io(struct completion *x)
 150 {
 151         wait_for_common_io(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
 152 }
 153 EXPORT_SYMBOL(wait_for_completion_io);
 154
 155 /**
 156  * wait_for_completion_io_timeout: - waits for completion of a task (w/timeout)
 157  * @x:  holds the state of this particular completion
 158  * @timeout:  timeout value in jiffies
 159  *
 160  * This waits for either a completion of a specific task to be signaled or for a
 161  * specified timeout to expire. The timeout is in jiffies. It is not
 162  * interruptible. The caller is accounted as waiting for IO (which traditionally
 163  * means blkio only).
 164  *
 165  * Return: 0 if timed out, and positive (at least 1, or number of jiffies left
 166  * till timeout) if completed.
 167  */
 168 unsigned long __sched
 169 wait_for_completion_io_timeout(struct completion *x, unsigned long timeout)
 170 {
 171         return wait_for_common_io(x, timeout, TASK_UNINTERRUPTIBLE);
 172 }
 173 EXPORT_SYMBOL(wait_for_completion_io_timeout);
 174
 175 /**
 176  * wait_for_completion_interruptible: - waits for completion of a task (w/intr)
 177  * @x:  holds the state of this particular completion
 178  *
 179  * This waits for completion of a specific task to be signaled. It is
 180  * interruptible.
 181  *
 182  * Return: -ERESTARTSYS if interrupted, 0 if completed.
 183  */
 184 int __sched wait_for_completion_interruptible(struct completion *x)
 185 {
 186         wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE);
 187         return 0;
 188 }
 189 EXPORT_SYMBOL(wait_for_completion_interruptible);
 190
 191 /**
 192  * wait_for_completion_interruptible_timeout: - waits for completion (w/(to,intr))
 193  * @x:  holds the state of this particular completion
 194  * @timeout:  timeout value in jiffies
 195  *
 196  * This waits for either a completion of a specific task to be signaled or for a
 197  * specified timeout to expire. It is interruptible. The timeout is in jiffies.
 198  *
 199  * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
 200  * or number of jiffies left till timeout) if completed.
 201  */
 202 long __sched
 203 wait_for_completion_interruptible_timeout(struct completion *x,
 204                                           unsigned long timeout)
 205 {
 206         return wait_for_common(x, timeout, TASK_INTERRUPTIBLE);
 207 }
 208 EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);
 209
 210 /**
 211  * wait_for_completion_killable: - waits for completion of a task (killable)
 212  * @x:  holds the state of this particular completion
 213  *
 214  * This waits to be signaled for completion of a specific task. It can be
 215  * interrupted by a kill signal.
 216  *
 217  * Return: -ERESTARTSYS if interrupted, 0 if completed.
 218  */
 219 int __sched wait_for_completion_killable(struct completion *x)
 220 {
 221         wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);
 222         return 0;
 223 }
 224 EXPORT_SYMBOL(wait_for_completion_killable);
 225
 226 /**
 227  * wait_for_completion_killable_timeout: - waits for completion of a task (w/(to,killable))
 228  * @x:  holds the state of this particular completion
 229  * @timeout:  timeout value in jiffies
 230  *
 231  * This waits for either a completion of a specific task to be
 232  * signaled or for a specified timeout to expire. It can be
 233  * interrupted by a kill signal. The timeout is in jiffies.
 234  *
 235  * Return: -ERESTARTSYS if interrupted, 0 if timed out, positive (at least 1,
 236  * or number of jiffies left till timeout) if completed.
 237  */
 238 long __sched
 239 wait_for_completion_killable_timeout(struct completion *x,
 240                                      unsigned long timeout)
 241 {
 242         return wait_for_common(x, timeout, TASK_KILLABLE);
 243 }
 244 EXPORT_SYMBOL(wait_for_completion_killable_timeout);
 245
 246 /**
 247  *      try_wait_for_completion - try to decrement a completion without blocking
 248  *      @x:     completion structure
 249  *
 250  *      Return: 0 if a decrement cannot be done without blocking
 251  *               1 if a decrement succeeded.
 252  *
 253  *      If a completion is being used as a counting completion,
 254  *      attempt to decrement the counter without blocking. This
 255  *      enables us to avoid waiting if the resource the completion
 256  *      is protecting is not available.
 257  */
 258 bool try_wait_for_completion(struct completion *x)
 259 {
 260         unsigned long flags;
 261         int ret = 1;
 262
 263         /*
 264          * Since x->done will need to be locked only
 265          * in the non-blocking case, we check x->done
 266          * first without taking the lock so we can
 267          * return early in the blocking case.
 268          */
 269         if (!READ_ONCE(x->done))
 270                 return 0;
 271
 272         spin_lock_irqsave(&x->wait.lock, flags);
 273         if (!x->done)
 274                 ret = 0;
 275         else
 276                 x->done--;
 277         spin_unlock_irqrestore(&x->wait.lock, flags);
 278         return ret;
 279 }
 280 EXPORT_SYMBOL(try_wait_for_completion);
 281
 282 /**
 283  *      completion_done - Test to see if a completion has any waiters
 284  *      @x:     completion structure
 285  *
 286  *      Return: 0 if there are waiters (wait_for_completion() in progress)
 287  *               1 if there are no waiters.
 288  *
 289  */
 290 bool completion_done(struct completion *x)
 291 {
 292         if (!READ_ONCE(x->done))
 293                 return false;
 294
 295         /*
 296          * If ->done, we need to wait for complete() to release ->wait.lock
 297          * otherwise we can end up freeing the completion before complete()
 298          * is done referencing it.
 299          *
 300          * The RMB pairs with complete()'s RELEASE of ->wait.lock and orders
 301          * the loads of ->done and ->wait.lock such that we cannot observe
 302          * the lock before complete() acquires it while observing the ->done
 303          * after it's acquired the lock.
 304          */
 305         smp_rmb();
 306         //spin_unlock_wait(&x->wait.lock);
 307         spin_lock(&x->wait.lock);
 308         spin_unlock(&x->wait.lock);
 309         return true;
 310 }
 311 EXPORT_SYMBOL(completion_done);