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