454 lines
14 KiB
C
454 lines
14 KiB
C
/*
|
|
* CDDL HEADER START
|
|
*
|
|
* This file and its contents are supplied under the terms of the
|
|
* Common Development and Distribution License ("CDDL"), version 1.0.
|
|
* You may only use this file in accordance with the terms of version
|
|
* 1.0 of the CDDL.
|
|
*
|
|
* A full copy of the text of the CDDL should have accompanied this
|
|
* source. A copy of the CDDL is also available via the Internet at
|
|
* http://www.illumos.org/license/CDDL.
|
|
*
|
|
* CDDL HEADER END
|
|
*/
|
|
|
|
/*
|
|
* Copyright (c) 2017, 2019 by Delphix. All rights reserved.
|
|
*/
|
|
|
|
/*
|
|
* ZTHR Infrastructure
|
|
* ===================
|
|
*
|
|
* ZTHR threads are used for isolated operations that span multiple txgs
|
|
* within a SPA. They generally exist from SPA creation/loading and until
|
|
* the SPA is exported/destroyed. The ideal requirements for an operation
|
|
* to be modeled with a zthr are the following:
|
|
*
|
|
* 1] The operation needs to run over multiple txgs.
|
|
* 2] There is be a single point of reference in memory or on disk that
|
|
* indicates whether the operation should run/is running or has
|
|
* stopped.
|
|
*
|
|
* If the operation satisfies the above then the following rules guarantee
|
|
* a certain level of correctness:
|
|
*
|
|
* 1] Any thread EXCEPT the zthr changes the work indicator from stopped
|
|
* to running but not the opposite.
|
|
* 2] Only the zthr can change the work indicator from running to stopped
|
|
* (e.g. when it is done) but not the opposite.
|
|
*
|
|
* This way a normal zthr cycle should go like this:
|
|
*
|
|
* 1] An external thread changes the work indicator from stopped to
|
|
* running and wakes up the zthr.
|
|
* 2] The zthr wakes up, checks the indicator and starts working.
|
|
* 3] When the zthr is done, it changes the indicator to stopped, allowing
|
|
* a new cycle to start.
|
|
*
|
|
* Besides being awakened by other threads, a zthr can be configured
|
|
* during creation to wakeup on its own after a specified interval
|
|
* [see zthr_create_timer()].
|
|
*
|
|
* Note: ZTHR threads are NOT a replacement for generic threads! Please
|
|
* ensure that they fit your use-case well before using them.
|
|
*
|
|
* == ZTHR creation
|
|
*
|
|
* Every zthr needs three inputs to start running:
|
|
*
|
|
* 1] A user-defined checker function (checkfunc) that decides whether
|
|
* the zthr should start working or go to sleep. The function should
|
|
* return TRUE when the zthr needs to work or FALSE to let it sleep,
|
|
* and should adhere to the following signature:
|
|
* boolean_t checkfunc_name(void *args, zthr_t *t);
|
|
*
|
|
* 2] A user-defined ZTHR function (func) which the zthr executes when
|
|
* it is not sleeping. The function should adhere to the following
|
|
* signature type:
|
|
* void func_name(void *args, zthr_t *t);
|
|
*
|
|
* 3] A void args pointer that will be passed to checkfunc and func
|
|
* implicitly by the infrastructure.
|
|
*
|
|
* The reason why the above API needs two different functions,
|
|
* instead of one that both checks and does the work, has to do with
|
|
* the zthr's internal state lock (zthr_state_lock) and the allowed
|
|
* cancellation windows. We want to hold the zthr_state_lock while
|
|
* running checkfunc but not while running func. This way the zthr
|
|
* can be cancelled while doing work and not while checking for work.
|
|
*
|
|
* To start a zthr:
|
|
* zthr_t *zthr_pointer = zthr_create(checkfunc, func, args);
|
|
* or
|
|
* zthr_t *zthr_pointer = zthr_create_timer(checkfunc, func,
|
|
* args, max_sleep);
|
|
*
|
|
* After that you should be able to wakeup, cancel, and resume the
|
|
* zthr from another thread using the zthr_pointer.
|
|
*
|
|
* NOTE: ZTHR threads could potentially wake up spuriously and the
|
|
* user should take this into account when writing a checkfunc.
|
|
* [see ZTHR state transitions]
|
|
*
|
|
* == ZTHR wakeup
|
|
*
|
|
* ZTHR wakeup should be used when new work is added for the zthr. The
|
|
* sleeping zthr will wakeup, see that it has more work to complete
|
|
* and proceed. This can be invoked from open or syncing context.
|
|
*
|
|
* To wakeup a zthr:
|
|
* zthr_wakeup(zthr_t *t)
|
|
*
|
|
* == ZTHR cancellation and resumption
|
|
*
|
|
* ZTHR threads must be cancelled when their SPA is being exported
|
|
* or when they need to be paused so they don't interfere with other
|
|
* operations.
|
|
*
|
|
* To cancel a zthr:
|
|
* zthr_cancel(zthr_pointer);
|
|
*
|
|
* To resume it:
|
|
* zthr_resume(zthr_pointer);
|
|
*
|
|
* ZTHR cancel and resume should be invoked in open context during the
|
|
* lifecycle of the pool as it is imported, exported or destroyed.
|
|
*
|
|
* A zthr will implicitly check if it has received a cancellation
|
|
* signal every time func returns and every time it wakes up [see
|
|
* ZTHR state transitions below].
|
|
*
|
|
* At times, waiting for the zthr's func to finish its job may take
|
|
* time. This may be very time-consuming for some operations that
|
|
* need to cancel the SPA's zthrs (e.g spa_export). For this scenario
|
|
* the user can explicitly make their ZTHR function aware of incoming
|
|
* cancellation signals using zthr_iscancelled(). A common pattern for
|
|
* that looks like this:
|
|
*
|
|
* int
|
|
* func_name(void *args, zthr_t *t)
|
|
* {
|
|
* ... <unpack args> ...
|
|
* while (!work_done && !zthr_iscancelled(t)) {
|
|
* ... <do more work> ...
|
|
* }
|
|
* }
|
|
*
|
|
* == ZTHR cleanup
|
|
*
|
|
* Cancelling a zthr doesn't clean up its metadata (internal locks,
|
|
* function pointers to func and checkfunc, etc..). This is because
|
|
* we want to keep them around in case we want to resume the execution
|
|
* of the zthr later. Similarly for zthrs that exit themselves.
|
|
*
|
|
* To completely cleanup a zthr, cancel it first to ensure that it
|
|
* is not running and then use zthr_destroy().
|
|
*
|
|
* == ZTHR state transitions
|
|
*
|
|
* zthr creation
|
|
* +
|
|
* |
|
|
* | woke up
|
|
* | +--------------+ sleep
|
|
* | | ^
|
|
* | | |
|
|
* | | | FALSE
|
|
* | | |
|
|
* v v FALSE +
|
|
* cancelled? +---------> checkfunc?
|
|
* + ^ +
|
|
* | | |
|
|
* | | | TRUE
|
|
* | | |
|
|
* | | func returned v
|
|
* | +---------------+ func
|
|
* |
|
|
* | TRUE
|
|
* |
|
|
* v
|
|
* zthr stopped running
|
|
*
|
|
* == Implementation of ZTHR requests
|
|
*
|
|
* ZTHR cancel and resume are requests on a zthr to change its
|
|
* internal state. These requests are serialized using the
|
|
* zthr_request_lock, while changes in its internal state are
|
|
* protected by the zthr_state_lock. A request will first acquire
|
|
* the zthr_request_lock and then immediately acquire the
|
|
* zthr_state_lock. We do this so that incoming requests are
|
|
* serialized using the request lock, while still allowing us
|
|
* to use the state lock for thread communication via zthr_cv.
|
|
*
|
|
* ZTHR wakeup broadcasts to zthr_cv, causing sleeping threads
|
|
* to wakeup. It acquires the zthr_state_lock but not the
|
|
* zthr_request_lock, so that a wakeup on a zthr in the middle
|
|
* of being cancelled will not block.
|
|
*/
|
|
|
|
#include <sys/zfs_context.h>
|
|
#include <sys/zthr.h>
|
|
|
|
struct zthr {
|
|
/* running thread doing the work */
|
|
kthread_t *zthr_thread;
|
|
|
|
/* lock protecting internal data & invariants */
|
|
kmutex_t zthr_state_lock;
|
|
|
|
/* mutex that serializes external requests */
|
|
kmutex_t zthr_request_lock;
|
|
|
|
/* notification mechanism for requests */
|
|
kcondvar_t zthr_cv;
|
|
|
|
/* flag set to true if we are canceling the zthr */
|
|
boolean_t zthr_cancel;
|
|
|
|
/*
|
|
* maximum amount of time that the zthr is spent sleeping;
|
|
* if this is 0, the thread doesn't wake up until it gets
|
|
* signaled.
|
|
*/
|
|
hrtime_t zthr_wait_time;
|
|
|
|
/* consumer-provided callbacks & data */
|
|
zthr_checkfunc_t *zthr_checkfunc;
|
|
zthr_func_t *zthr_func;
|
|
void *zthr_arg;
|
|
};
|
|
|
|
static void
|
|
zthr_procedure(void *arg)
|
|
{
|
|
zthr_t *t = arg;
|
|
|
|
mutex_enter(&t->zthr_state_lock);
|
|
ASSERT3P(t->zthr_thread, ==, curthread);
|
|
|
|
while (!t->zthr_cancel) {
|
|
if (t->zthr_checkfunc(t->zthr_arg, t)) {
|
|
mutex_exit(&t->zthr_state_lock);
|
|
t->zthr_func(t->zthr_arg, t);
|
|
mutex_enter(&t->zthr_state_lock);
|
|
} else {
|
|
/*
|
|
* cv_wait_sig() is used instead of cv_wait() in
|
|
* order to prevent this process from incorrectly
|
|
* contributing to the system load average when idle.
|
|
*/
|
|
if (t->zthr_wait_time == 0) {
|
|
cv_wait_sig(&t->zthr_cv, &t->zthr_state_lock);
|
|
} else {
|
|
(void) cv_timedwait_sig_hires(&t->zthr_cv,
|
|
&t->zthr_state_lock, t->zthr_wait_time,
|
|
MSEC2NSEC(1), 0);
|
|
}
|
|
}
|
|
}
|
|
|
|
/*
|
|
* Clear out the kernel thread metadata and notify the
|
|
* zthr_cancel() thread that we've stopped running.
|
|
*/
|
|
t->zthr_thread = NULL;
|
|
t->zthr_cancel = B_FALSE;
|
|
cv_broadcast(&t->zthr_cv);
|
|
|
|
mutex_exit(&t->zthr_state_lock);
|
|
thread_exit();
|
|
}
|
|
|
|
zthr_t *
|
|
zthr_create(zthr_checkfunc_t *checkfunc, zthr_func_t *func, void *arg)
|
|
{
|
|
return (zthr_create_timer(checkfunc, func, arg, (hrtime_t)0));
|
|
}
|
|
|
|
/*
|
|
* Create a zthr with specified maximum sleep time. If the time
|
|
* in sleeping state exceeds max_sleep, a wakeup(do the check and
|
|
* start working if required) will be triggered.
|
|
*/
|
|
zthr_t *
|
|
zthr_create_timer(zthr_checkfunc_t *checkfunc, zthr_func_t *func,
|
|
void *arg, hrtime_t max_sleep)
|
|
{
|
|
zthr_t *t = kmem_zalloc(sizeof (*t), KM_SLEEP);
|
|
mutex_init(&t->zthr_state_lock, NULL, MUTEX_DEFAULT, NULL);
|
|
mutex_init(&t->zthr_request_lock, NULL, MUTEX_DEFAULT, NULL);
|
|
cv_init(&t->zthr_cv, NULL, CV_DEFAULT, NULL);
|
|
|
|
mutex_enter(&t->zthr_state_lock);
|
|
t->zthr_checkfunc = checkfunc;
|
|
t->zthr_func = func;
|
|
t->zthr_arg = arg;
|
|
t->zthr_wait_time = max_sleep;
|
|
|
|
t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
|
|
0, &p0, TS_RUN, minclsyspri);
|
|
mutex_exit(&t->zthr_state_lock);
|
|
|
|
return (t);
|
|
}
|
|
|
|
void
|
|
zthr_destroy(zthr_t *t)
|
|
{
|
|
ASSERT(!MUTEX_HELD(&t->zthr_state_lock));
|
|
ASSERT(!MUTEX_HELD(&t->zthr_request_lock));
|
|
VERIFY3P(t->zthr_thread, ==, NULL);
|
|
mutex_destroy(&t->zthr_request_lock);
|
|
mutex_destroy(&t->zthr_state_lock);
|
|
cv_destroy(&t->zthr_cv);
|
|
kmem_free(t, sizeof (*t));
|
|
}
|
|
|
|
/*
|
|
* Wake up the zthr if it is sleeping. If the thread has been cancelled
|
|
* or is in the process of being cancelled, this is a no-op.
|
|
*/
|
|
void
|
|
zthr_wakeup(zthr_t *t)
|
|
{
|
|
mutex_enter(&t->zthr_state_lock);
|
|
|
|
/*
|
|
* There are 5 states that we can find the zthr when issuing
|
|
* this broadcast:
|
|
*
|
|
* [1] The common case of the thread being asleep, at which
|
|
* point the broadcast will wake it up.
|
|
* [2] The thread has been cancelled. Waking up a cancelled
|
|
* thread is a no-op. Any work that is still left to be
|
|
* done should be handled the next time the thread is
|
|
* resumed.
|
|
* [3] The thread is doing work and is already up, so this
|
|
* is basically a no-op.
|
|
* [4] The thread was just created/resumed, in which case the
|
|
* behavior is similar to [3].
|
|
* [5] The thread is in the middle of being cancelled, which
|
|
* will be a no-op.
|
|
*/
|
|
cv_broadcast(&t->zthr_cv);
|
|
|
|
mutex_exit(&t->zthr_state_lock);
|
|
}
|
|
|
|
/*
|
|
* Sends a cancel request to the zthr and blocks until the zthr is
|
|
* cancelled. If the zthr is not running (e.g. has been cancelled
|
|
* already), this is a no-op. Note that this function should not be
|
|
* called from syncing context as it could deadlock with the zthr_func.
|
|
*/
|
|
void
|
|
zthr_cancel(zthr_t *t)
|
|
{
|
|
mutex_enter(&t->zthr_request_lock);
|
|
mutex_enter(&t->zthr_state_lock);
|
|
|
|
/*
|
|
* Since we are holding the zthr_state_lock at this point
|
|
* we can find the state in one of the following 4 states:
|
|
*
|
|
* [1] The thread has already been cancelled, therefore
|
|
* there is nothing for us to do.
|
|
* [2] The thread is sleeping, so we broadcast the CV first
|
|
* to wake it up and then we set the flag and we are
|
|
* waiting for it to exit.
|
|
* [3] The thread is doing work, in which case we just set
|
|
* the flag and wait for it to finish.
|
|
* [4] The thread was just created/resumed, in which case
|
|
* the behavior is similar to [3].
|
|
*
|
|
* Since requests are serialized, by the time that we get
|
|
* control back we expect that the zthr is cancelled and
|
|
* not running anymore.
|
|
*/
|
|
if (t->zthr_thread != NULL) {
|
|
t->zthr_cancel = B_TRUE;
|
|
|
|
/* broadcast in case the zthr is sleeping */
|
|
cv_broadcast(&t->zthr_cv);
|
|
|
|
while (t->zthr_thread != NULL)
|
|
cv_wait(&t->zthr_cv, &t->zthr_state_lock);
|
|
|
|
ASSERT(!t->zthr_cancel);
|
|
}
|
|
|
|
mutex_exit(&t->zthr_state_lock);
|
|
mutex_exit(&t->zthr_request_lock);
|
|
}
|
|
|
|
/*
|
|
* Sends a resume request to the supplied zthr. If the zthr is already
|
|
* running this is a no-op. Note that this function should not be
|
|
* called from syncing context as it could deadlock with the zthr_func.
|
|
*/
|
|
void
|
|
zthr_resume(zthr_t *t)
|
|
{
|
|
mutex_enter(&t->zthr_request_lock);
|
|
mutex_enter(&t->zthr_state_lock);
|
|
|
|
ASSERT3P(&t->zthr_checkfunc, !=, NULL);
|
|
ASSERT3P(&t->zthr_func, !=, NULL);
|
|
ASSERT(!t->zthr_cancel);
|
|
|
|
/*
|
|
* There are 4 states that we find the zthr in at this point
|
|
* given the locks that we hold:
|
|
*
|
|
* [1] The zthr was cancelled, so we spawn a new thread for
|
|
* the zthr (common case).
|
|
* [2] The zthr is running at which point this is a no-op.
|
|
* [3] The zthr is sleeping at which point this is a no-op.
|
|
* [4] The zthr was just spawned at which point this is a
|
|
* no-op.
|
|
*/
|
|
if (t->zthr_thread == NULL) {
|
|
t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
|
|
0, &p0, TS_RUN, minclsyspri);
|
|
}
|
|
|
|
mutex_exit(&t->zthr_state_lock);
|
|
mutex_exit(&t->zthr_request_lock);
|
|
}
|
|
|
|
/*
|
|
* This function is intended to be used by the zthr itself
|
|
* (specifically the zthr_func callback provided) to check
|
|
* if another thread has signaled it to stop running before
|
|
* doing some expensive operation.
|
|
*
|
|
* returns TRUE if we are in the middle of trying to cancel
|
|
* this thread.
|
|
*
|
|
* returns FALSE otherwise.
|
|
*/
|
|
boolean_t
|
|
zthr_iscancelled(zthr_t *t)
|
|
{
|
|
ASSERT3P(t->zthr_thread, ==, curthread);
|
|
|
|
/*
|
|
* The majority of the functions here grab zthr_request_lock
|
|
* first and then zthr_state_lock. This function only grabs
|
|
* the zthr_state_lock. That is because this function should
|
|
* only be called from the zthr_func to check if someone has
|
|
* issued a zthr_cancel() on the thread. If there is a zthr_cancel()
|
|
* happening concurrently, attempting to grab the request lock
|
|
* here would result in a deadlock.
|
|
*
|
|
* By grabbing only the zthr_state_lock this function is allowed
|
|
* to run concurrently with a zthr_cancel() request.
|
|
*/
|
|
mutex_enter(&t->zthr_state_lock);
|
|
boolean_t cancelled = t->zthr_cancel;
|
|
mutex_exit(&t->zthr_state_lock);
|
|
return (cancelled);
|
|
}
|