sys/contrib/openzfs/module/zfs/zthr.c

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * This file and its contents are supplied under the terms of the
   5  * Common Development and Distribution License ("CDDL"), version 1.0.
   6  * You may only use this file in accordance with the terms of version
   7  * 1.0 of the CDDL.
   8  *
   9  * A full copy of the text of the CDDL should have accompanied this
  10  * source. A copy of the CDDL is also available via the Internet at
  11  * http://www.illumos.org/license/CDDL.
  12  *
  13  * CDDL HEADER END
  14  */
  15
  16 /*
  17  * Copyright (c) 2017, 2020 by Delphix. All rights reserved.
  18  */
  19
  20 /*
  21  * ZTHR Infrastructure
  22  * ===================
  23  *
  24  * ZTHR threads are used for isolated operations that span multiple txgs
  25  * within a SPA. They generally exist from SPA creation/loading and until
  26  * the SPA is exported/destroyed. The ideal requirements for an operation
  27  * to be modeled with a zthr are the following:
  28  *
  29  * 1] The operation needs to run over multiple txgs.
  30  * 2] There is be a single point of reference in memory or on disk that
  31  *    indicates whether the operation should run/is running or has
  32  *    stopped.
  33  *
  34  * If the operation satisfies the above then the following rules guarantee
  35  * a certain level of correctness:
  36  *
  37  * 1] Any thread EXCEPT the zthr changes the work indicator from stopped
  38  *    to running but not the opposite.
  39  * 2] Only the zthr can change the work indicator from running to stopped
  40  *    (e.g. when it is done) but not the opposite.
  41  *
  42  * This way a normal zthr cycle should go like this:
  43  *
  44  * 1] An external thread changes the work indicator from stopped to
  45  *    running and wakes up the zthr.
  46  * 2] The zthr wakes up, checks the indicator and starts working.
  47  * 3] When the zthr is done, it changes the indicator to stopped, allowing
  48  *    a new cycle to start.
  49  *
  50  * Besides being awakened by other threads, a zthr can be configured
  51  * during creation to wakeup on its own after a specified interval
  52  * [see zthr_create_timer()].
  53  *
  54  * Note: ZTHR threads are NOT a replacement for generic threads! Please
  55  * ensure that they fit your use-case well before using them.
  56  *
  57  * == ZTHR creation
  58  *
  59  * Every zthr needs four inputs to start running:
  60  *
  61  * 1] A user-defined checker function (checkfunc) that decides whether
  62  *    the zthr should start working or go to sleep. The function should
  63  *    return TRUE when the zthr needs to work or FALSE to let it sleep,
  64  *    and should adhere to the following signature:
  65  *    boolean_t checkfunc_name(void *args, zthr_t *t);
  66  *
  67  * 2] A user-defined ZTHR function (func) which the zthr executes when
  68  *    it is not sleeping. The function should adhere to the following
  69  *    signature type:
  70  *    void func_name(void *args, zthr_t *t);
  71  *
  72  * 3] A void args pointer that will be passed to checkfunc and func
  73  *    implicitly by the infrastructure.
  74  *
  75  * 4] A name for the thread. This string must be valid for the lifetime
  76  *    of the zthr.
  77  *
  78  * The reason why the above API needs two different functions,
  79  * instead of one that both checks and does the work, has to do with
  80  * the zthr's internal state lock (zthr_state_lock) and the allowed
  81  * cancellation windows. We want to hold the zthr_state_lock while
  82  * running checkfunc but not while running func. This way the zthr
  83  * can be cancelled while doing work and not while checking for work.
  84  *
  85  * To start a zthr:
  86  *     zthr_t *zthr_pointer = zthr_create(checkfunc, func, args,
  87  *         pri);
  88  * or
  89  *     zthr_t *zthr_pointer = zthr_create_timer(checkfunc, func,
  90  *         args, max_sleep, pri);
  91  *
  92  * After that you should be able to wakeup, cancel, and resume the
  93  * zthr from another thread using the zthr_pointer.
  94  *
  95  * NOTE: ZTHR threads could potentially wake up spuriously and the
  96  * user should take this into account when writing a checkfunc.
  97  * [see ZTHR state transitions]
  98  *
  99  * == ZTHR wakeup
 100  *
 101  * ZTHR wakeup should be used when new work is added for the zthr. The
 102  * sleeping zthr will wakeup, see that it has more work to complete
 103  * and proceed. This can be invoked from open or syncing context.
 104  *
 105  * To wakeup a zthr:
 106  *     zthr_wakeup(zthr_t *t)
 107  *
 108  * == ZTHR cancellation and resumption
 109  *
 110  * ZTHR threads must be cancelled when their SPA is being exported
 111  * or when they need to be paused so they don't interfere with other
 112  * operations.
 113  *
 114  * To cancel a zthr:
 115  *     zthr_cancel(zthr_pointer);
 116  *
 117  * To resume it:
 118  *     zthr_resume(zthr_pointer);
 119  *
 120  * ZTHR cancel and resume should be invoked in open context during the
 121  * lifecycle of the pool as it is imported, exported or destroyed.
 122  *
 123  * A zthr will implicitly check if it has received a cancellation
 124  * signal every time func returns and every time it wakes up [see
 125  * ZTHR state transitions below].
 126  *
 127  * At times, waiting for the zthr's func to finish its job may take
 128  * time. This may be very time-consuming for some operations that
 129  * need to cancel the SPA's zthrs (e.g spa_export). For this scenario
 130  * the user can explicitly make their ZTHR function aware of incoming
 131  * cancellation signals using zthr_iscancelled(). A common pattern for
 132  * that looks like this:
 133  *
 134  * int
 135  * func_name(void *args, zthr_t *t)
 136  * {
 137  *     ... <unpack args> ...
 138  *     while (!work_done && !zthr_iscancelled(t)) {
 139  *         ... <do more work> ...
 140  *     }
 141  * }
 142  *
 143  * == ZTHR cleanup
 144  *
 145  * Cancelling a zthr doesn't clean up its metadata (internal locks,
 146  * function pointers to func and checkfunc, etc..). This is because
 147  * we want to keep them around in case we want to resume the execution
 148  * of the zthr later. Similarly for zthrs that exit themselves.
 149  *
 150  * To completely cleanup a zthr, cancel it first to ensure that it
 151  * is not running and then use zthr_destroy().
 152  *
 153  * == ZTHR state transitions
 154  *
 155  *    zthr creation
 156  *      +
 157  *      |
 158  *      |      woke up
 159  *      |   +--------------+ sleep
 160  *      |   |                  ^
 161  *      |   |                  |
 162  *      |   |                  | FALSE
 163  *      |   |                  |
 164  *      v   v     FALSE        +
 165  *   cancelled? +---------> checkfunc?
 166  *      +   ^                  +
 167  *      |   |                  |
 168  *      |   |                  | TRUE
 169  *      |   |                  |
 170  *      |   |  func returned   v
 171  *      |   +---------------+ func
 172  *      |
 173  *      | TRUE
 174  *      |
 175  *      v
 176  *   zthr stopped running
 177  *
 178  * == Implementation of ZTHR requests
 179  *
 180  * ZTHR cancel and resume are requests on a zthr to change its
 181  * internal state. These requests are serialized using the
 182  * zthr_request_lock, while changes in its internal state are
 183  * protected by the zthr_state_lock. A request will first acquire
 184  * the zthr_request_lock and then immediately acquire the
 185  * zthr_state_lock. We do this so that incoming requests are
 186  * serialized using the request lock, while still allowing us
 187  * to use the state lock for thread communication via zthr_cv.
 188  *
 189  * ZTHR wakeup broadcasts to zthr_cv, causing sleeping threads
 190  * to wakeup. It acquires the zthr_state_lock but not the
 191  * zthr_request_lock, so that a wakeup on a zthr in the middle
 192  * of being cancelled will not block.
 193  */
 194
 195 #include <sys/zfs_context.h>
 196 #include <sys/zthr.h>
 197
 198 struct zthr {
 199         /* running thread doing the work */
 200         kthread_t       *zthr_thread;
 201
 202         /* lock protecting internal data & invariants */
 203         kmutex_t        zthr_state_lock;
 204
 205         /* mutex that serializes external requests */
 206         kmutex_t        zthr_request_lock;
 207
 208         /* notification mechanism for requests */
 209         kcondvar_t      zthr_cv;
 210
 211         /* flag set to true if we are canceling the zthr */
 212         boolean_t       zthr_cancel;
 213
 214         /* flag set to true if we are waiting for the zthr to finish */
 215         boolean_t       zthr_haswaiters;
 216         kcondvar_t      zthr_wait_cv;
 217         /*
 218          * maximum amount of time that the zthr is spent sleeping;
 219          * if this is 0, the thread doesn't wake up until it gets
 220          * signaled.
 221          */
 222         hrtime_t        zthr_sleep_timeout;
 223
 224         /* Thread priority */
 225         pri_t           zthr_pri;
 226
 227         /* consumer-provided callbacks & data */
 228         zthr_checkfunc_t        *zthr_checkfunc;
 229         zthr_func_t     *zthr_func;
 230         void            *zthr_arg;
 231         const char      *zthr_name;
 232 };
 233
 234 static __attribute__((noreturn)) void
 235 zthr_procedure(void *arg)
 236 {
 237         zthr_t *t = arg;
 238
 239         mutex_enter(&t->zthr_state_lock);
 240         ASSERT3P(t->zthr_thread, ==, curthread);
 241
 242         while (!t->zthr_cancel) {
 243                 if (t->zthr_checkfunc(t->zthr_arg, t)) {
 244                         mutex_exit(&t->zthr_state_lock);
 245                         t->zthr_func(t->zthr_arg, t);
 246                         mutex_enter(&t->zthr_state_lock);
 247                 } else {
 248                         if (t->zthr_sleep_timeout == 0) {
 249                                 cv_wait_idle(&t->zthr_cv, &t->zthr_state_lock);
 250                         } else {
 251                                 (void) cv_timedwait_idle_hires(&t->zthr_cv,
 252                                     &t->zthr_state_lock, t->zthr_sleep_timeout,
 253                                     MSEC2NSEC(1), 0);
 254                         }
 255                 }
 256                 if (t->zthr_haswaiters) {
 257                         t->zthr_haswaiters = B_FALSE;
 258                         cv_broadcast(&t->zthr_wait_cv);
 259                 }
 260         }
 261
 262         /*
 263          * Clear out the kernel thread metadata and notify the
 264          * zthr_cancel() thread that we've stopped running.
 265          */
 266         t->zthr_thread = NULL;
 267         t->zthr_cancel = B_FALSE;
 268         cv_broadcast(&t->zthr_cv);
 269
 270         mutex_exit(&t->zthr_state_lock);
 271         thread_exit();
 272 }
 273
 274 zthr_t *
 275 zthr_create(const char *zthr_name, zthr_checkfunc_t *checkfunc,
 276     zthr_func_t *func, void *arg, pri_t pri)
 277 {
 278         return (zthr_create_timer(zthr_name, checkfunc,
 279             func, arg, (hrtime_t)0, pri));
 280 }
 281
 282 /*
 283  * Create a zthr with specified maximum sleep time.  If the time
 284  * in sleeping state exceeds max_sleep, a wakeup(do the check and
 285  * start working if required) will be triggered.
 286  */
 287 zthr_t *
 288 zthr_create_timer(const char *zthr_name, zthr_checkfunc_t *checkfunc,
 289     zthr_func_t *func, void *arg, hrtime_t max_sleep, pri_t pri)
 290 {
 291         zthr_t *t = kmem_zalloc(sizeof (*t), KM_SLEEP);
 292         mutex_init(&t->zthr_state_lock, NULL, MUTEX_DEFAULT, NULL);
 293         mutex_init(&t->zthr_request_lock, NULL, MUTEX_DEFAULT, NULL);
 294         cv_init(&t->zthr_cv, NULL, CV_DEFAULT, NULL);
 295         cv_init(&t->zthr_wait_cv, NULL, CV_DEFAULT, NULL);
 296
 297         mutex_enter(&t->zthr_state_lock);
 298         t->zthr_checkfunc = checkfunc;
 299         t->zthr_func = func;
 300         t->zthr_arg = arg;
 301         t->zthr_sleep_timeout = max_sleep;
 302         t->zthr_name = zthr_name;
 303         t->zthr_pri = pri;
 304
 305         t->zthr_thread = thread_create_named(zthr_name, NULL, 0,
 306             zthr_procedure, t, 0, &p0, TS_RUN, pri);
 307
 308         mutex_exit(&t->zthr_state_lock);
 309
 310         return (t);
 311 }
 312
 313 void
 314 zthr_destroy(zthr_t *t)
 315 {
 316         ASSERT(!MUTEX_HELD(&t->zthr_state_lock));
 317         ASSERT(!MUTEX_HELD(&t->zthr_request_lock));
 318         VERIFY3P(t->zthr_thread, ==, NULL);
 319         mutex_destroy(&t->zthr_request_lock);
 320         mutex_destroy(&t->zthr_state_lock);
 321         cv_destroy(&t->zthr_cv);
 322         cv_destroy(&t->zthr_wait_cv);
 323         kmem_free(t, sizeof (*t));
 324 }
 325
 326 /*
 327  * Wake up the zthr if it is sleeping. If the thread has been cancelled
 328  * or is in the process of being cancelled, this is a no-op.
 329  */
 330 void
 331 zthr_wakeup(zthr_t *t)
 332 {
 333         mutex_enter(&t->zthr_state_lock);
 334
 335         /*
 336          * There are 5 states that we can find the zthr when issuing
 337          * this broadcast:
 338          *
 339          * [1] The common case of the thread being asleep, at which
 340          *     point the broadcast will wake it up.
 341          * [2] The thread has been cancelled. Waking up a cancelled
 342          *     thread is a no-op. Any work that is still left to be
 343          *     done should be handled the next time the thread is
 344          *     resumed.
 345          * [3] The thread is doing work and is already up, so this
 346          *     is basically a no-op.
 347          * [4] The thread was just created/resumed, in which case the
 348          *     behavior is similar to [3].
 349          * [5] The thread is in the middle of being cancelled, which
 350          *     will be a no-op.
 351          */
 352         cv_broadcast(&t->zthr_cv);
 353
 354         mutex_exit(&t->zthr_state_lock);
 355 }
 356
 357 /*
 358  * Sends a cancel request to the zthr and blocks until the zthr is
 359  * cancelled. If the zthr is not running (e.g. has been cancelled
 360  * already), this is a no-op. Note that this function should not be
 361  * called from syncing context as it could deadlock with the zthr_func.
 362  */
 363 void
 364 zthr_cancel(zthr_t *t)
 365 {
 366         mutex_enter(&t->zthr_request_lock);
 367         mutex_enter(&t->zthr_state_lock);
 368
 369         /*
 370          * Since we are holding the zthr_state_lock at this point
 371          * we can find the state in one of the following 4 states:
 372          *
 373          * [1] The thread has already been cancelled, therefore
 374          *     there is nothing for us to do.
 375          * [2] The thread is sleeping so we set the flag, broadcast
 376          *     the CV and wait for it to exit.
 377          * [3] The thread is doing work, in which case we just set
 378          *     the flag and wait for it to finish.
 379          * [4] The thread was just created/resumed, in which case
 380          *     the behavior is similar to [3].
 381          *
 382          * Since requests are serialized, by the time that we get
 383          * control back we expect that the zthr is cancelled and
 384          * not running anymore.
 385          */
 386         if (t->zthr_thread != NULL) {
 387                 t->zthr_cancel = B_TRUE;
 388
 389                 /* broadcast in case the zthr is sleeping */
 390                 cv_broadcast(&t->zthr_cv);
 391
 392                 while (t->zthr_thread != NULL)
 393                         cv_wait(&t->zthr_cv, &t->zthr_state_lock);
 394
 395                 ASSERT(!t->zthr_cancel);
 396         }
 397
 398         mutex_exit(&t->zthr_state_lock);
 399         mutex_exit(&t->zthr_request_lock);
 400 }
 401
 402 /*
 403  * Sends a resume request to the supplied zthr. If the zthr is already
 404  * running this is a no-op. Note that this function should not be
 405  * called from syncing context as it could deadlock with the zthr_func.
 406  */
 407 void
 408 zthr_resume(zthr_t *t)
 409 {
 410         mutex_enter(&t->zthr_request_lock);
 411         mutex_enter(&t->zthr_state_lock);
 412
 413         ASSERT3P(&t->zthr_checkfunc, !=, NULL);
 414         ASSERT3P(&t->zthr_func, !=, NULL);
 415         ASSERT(!t->zthr_cancel);
 416         ASSERT(!t->zthr_haswaiters);
 417
 418         /*
 419          * There are 4 states that we find the zthr in at this point
 420          * given the locks that we hold:
 421          *
 422          * [1] The zthr was cancelled, so we spawn a new thread for
 423          *     the zthr (common case).
 424          * [2] The zthr is running at which point this is a no-op.
 425          * [3] The zthr is sleeping at which point this is a no-op.
 426          * [4] The zthr was just spawned at which point this is a
 427          *     no-op.
 428          */
 429         if (t->zthr_thread == NULL) {
 430                 t->zthr_thread = thread_create_named(t->zthr_name, NULL, 0,
 431                     zthr_procedure, t, 0, &p0, TS_RUN, t->zthr_pri);
 432         }
 433
 434         mutex_exit(&t->zthr_state_lock);
 435         mutex_exit(&t->zthr_request_lock);
 436 }
 437
 438 /*
 439  * This function is intended to be used by the zthr itself
 440  * (specifically the zthr_func callback provided) to check
 441  * if another thread has signaled it to stop running before
 442  * doing some expensive operation.
 443  *
 444  * returns TRUE if we are in the middle of trying to cancel
 445  *     this thread.
 446  *
 447  * returns FALSE otherwise.
 448  */
 449 boolean_t
 450 zthr_iscancelled(zthr_t *t)
 451 {
 452         ASSERT3P(t->zthr_thread, ==, curthread);
 453
 454         /*
 455          * The majority of the functions here grab zthr_request_lock
 456          * first and then zthr_state_lock. This function only grabs
 457          * the zthr_state_lock. That is because this function should
 458          * only be called from the zthr_func to check if someone has
 459          * issued a zthr_cancel() on the thread. If there is a zthr_cancel()
 460          * happening concurrently, attempting to grab the request lock
 461          * here would result in a deadlock.
 462          *
 463          * By grabbing only the zthr_state_lock this function is allowed
 464          * to run concurrently with a zthr_cancel() request.
 465          */
 466         mutex_enter(&t->zthr_state_lock);
 467         boolean_t cancelled = t->zthr_cancel;
 468         mutex_exit(&t->zthr_state_lock);
 469         return (cancelled);
 470 }
 471
 472 boolean_t
 473 zthr_iscurthread(zthr_t *t)
 474 {
 475         return (t->zthr_thread == curthread);
 476 }
 477
 478 /*
 479  * Wait for the zthr to finish its current function. Similar to
 480  * zthr_iscancelled, you can use zthr_has_waiters to have the zthr_func end
 481  * early. Unlike zthr_cancel, the thread is not destroyed. If the zthr was
 482  * sleeping or cancelled, return immediately.
 483  */
 484 void
 485 zthr_wait_cycle_done(zthr_t *t)
 486 {
 487         mutex_enter(&t->zthr_state_lock);
 488
 489         /*
 490          * Since we are holding the zthr_state_lock at this point
 491          * we can find the state in one of the following 5 states:
 492          *
 493          * [1] The thread has already cancelled, therefore
 494          *     there is nothing for us to do.
 495          * [2] The thread is sleeping so we set the flag, broadcast
 496          *     the CV and wait for it to exit.
 497          * [3] The thread is doing work, in which case we just set
 498          *     the flag and wait for it to finish.
 499          * [4] The thread was just created/resumed, in which case
 500          *     the behavior is similar to [3].
 501          * [5] The thread is the middle of being cancelled, which is
 502          *     similar to [3]. We'll wait for the cancel, which is
 503          *     waiting for the zthr func.
 504          *
 505          * Since requests are serialized, by the time that we get
 506          * control back we expect that the zthr has completed it's
 507          * zthr_func.
 508          */
 509         if (t->zthr_thread != NULL) {
 510                 t->zthr_haswaiters = B_TRUE;
 511
 512                 /* broadcast in case the zthr is sleeping */
 513                 cv_broadcast(&t->zthr_cv);
 514
 515                 while ((t->zthr_haswaiters) && (t->zthr_thread != NULL))
 516                         cv_wait(&t->zthr_wait_cv, &t->zthr_state_lock);
 517
 518                 ASSERT(!t->zthr_haswaiters);
 519         }
 520
 521         mutex_exit(&t->zthr_state_lock);
 522 }
 523
 524 /*
 525  * This function is intended to be used by the zthr itself
 526  * to check if another thread is waiting on it to finish
 527  *
 528  * returns TRUE if we have been asked to finish.
 529  *
 530  * returns FALSE otherwise.
 531  */
 532 boolean_t
 533 zthr_has_waiters(zthr_t *t)
 534 {
 535         ASSERT3P(t->zthr_thread, ==, curthread);
 536
 537         mutex_enter(&t->zthr_state_lock);
 538
 539         /*
 540          * Similarly to zthr_iscancelled(), we only grab the
 541          * zthr_state_lock so that the zthr itself can use this
 542          * to check for the request.
 543          */
 544         boolean_t has_waiters = t->zthr_haswaiters;
 545         mutex_exit(&t->zthr_state_lock);
 546         return (has_waiters);
 547 }