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
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.
17 * Copyright (c) 2017 by Delphix. All rights reserved.
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:
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 is
34 * If the operation satisfies the above then the following rules guarantee
35 * a certain level of correctness:
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.
42 * This way a normal zthr cycle should go like this:
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.
52 * Every zthr needs three inputs to start running:
54 * 1] A user-defined checker function (checkfunc) that decides whether
55 * the zthr should start working or go to sleep. The function should
56 * return TRUE when the zthr needs to work or FALSE to let it sleep,
57 * and should adhere to the following signature:
58 * boolean_t checkfunc_name(void *args, zthr_t *t);
60 * 2] A user-defined ZTHR function (func) which the zthr executes when
61 * it is not sleeping. The function should adhere to the following
63 * int func_name(void *args, zthr_t *t);
65 * 3] A void args pointer that will be passed to checkfunc and func
66 * implicitly by the infrastructure.
68 * The reason why the above API needs two different functions,
69 * instead of one that both checks and does the work, has to do with
70 * the zthr's internal lock (zthr_lock) and the allowed cancellation
71 * windows. We want to hold the zthr_lock while running checkfunc
72 * but not while running func. This way the zthr can be cancelled
73 * while doing work and not while checking for work.
76 * zthr_t *zthr_pointer = zthr_create(checkfunc, func, args);
78 * After that you should be able to wakeup, cancel, and resume the
79 * zthr from another thread using zthr_pointer.
81 * NOTE: ZTHR threads could potentially wake up spuriously and the
82 * user should take this into account when writing a checkfunc.
83 * [see ZTHR state transitions]
85 * == ZTHR cancellation
87 * ZTHR threads must be cancelled when their SPA is being exported
88 * or when they need to be paused so they don't interfere with other
92 * zthr_cancel(zthr_pointer);
95 * zthr_resume(zthr_pointer);
97 * A zthr will implicitly check if it has received a cancellation
98 * signal every time func returns and everytime it wakes up [see ZTHR
99 * state transitions below].
101 * At times, waiting for the zthr's func to finish its job may take
102 * time. This may be very time-consuming for some operations that
103 * need to cancel the SPA's zthrs (e.g spa_export). For this scenario
104 * the user can explicitly make their ZTHR function aware of incoming
105 * cancellation signals using zthr_iscancelled(). A common pattern for
106 * that looks like this:
109 * func_name(void *args, zthr_t *t)
111 * ... <unpack args> ...
112 * while (!work_done && !zthr_iscancelled(t)) {
113 * ... <do more work> ...
120 * For the rare cases where the zthr wants to stop running voluntarily
121 * while running its ZTHR function (func), we provide zthr_exit().
122 * When a zthr has voluntarily stopped running, it can be resumed with
123 * zthr_resume(), just like it would if it was cancelled by some other
128 * Cancelling a zthr doesn't clean up its metadata (internal locks,
129 * function pointers to func and checkfunc, etc..). This is because
130 * we want to keep them around in case we want to resume the execution
131 * of the zthr later. Similarly for zthrs that exit themselves.
133 * To completely cleanup a zthr, cancel it first to ensure that it
134 * is not running and then use zthr_destroy().
136 * == ZTHR state transitions
142 * | +--------------+ sleep
148 * cancelled? +---------> checkfunc?
153 * | | func returned v
154 * | +---------------+ func
159 * zthr stopped running
163 #include <sys/zfs_context.h>
164 #include <sys/zthr.h>
167 zthr_exit(zthr_t *t, int rc)
169 ASSERT3P(t->zthr_thread, ==, curthread);
170 mutex_enter(&t->zthr_lock);
171 t->zthr_thread = NULL;
173 cv_broadcast(&t->zthr_cv);
174 mutex_exit(&t->zthr_lock);
179 zthr_procedure(void *arg)
184 mutex_enter(&t->zthr_lock);
185 while (!t->zthr_cancel) {
186 if (t->zthr_checkfunc(t->zthr_arg, t)) {
187 mutex_exit(&t->zthr_lock);
188 rc = t->zthr_func(t->zthr_arg, t);
189 mutex_enter(&t->zthr_lock);
192 cv_wait_sig(&t->zthr_cv, &t->zthr_lock);
195 mutex_exit(&t->zthr_lock);
201 zthr_create(zthr_checkfunc_t *checkfunc, zthr_func_t *func, void *arg)
203 zthr_t *t = kmem_zalloc(sizeof (*t), KM_SLEEP);
204 mutex_init(&t->zthr_lock, NULL, MUTEX_DEFAULT, NULL);
205 cv_init(&t->zthr_cv, NULL, CV_DEFAULT, NULL);
207 mutex_enter(&t->zthr_lock);
208 t->zthr_checkfunc = checkfunc;
212 t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
213 0, &p0, TS_RUN, minclsyspri);
214 mutex_exit(&t->zthr_lock);
220 zthr_destroy(zthr_t *t)
222 VERIFY3P(t->zthr_thread, ==, NULL);
223 mutex_destroy(&t->zthr_lock);
224 cv_destroy(&t->zthr_cv);
225 kmem_free(t, sizeof (*t));
229 * Note: If the zthr is not sleeping and misses the wakeup
230 * (e.g it is running its ZTHR function), it will check if
231 * there is work to do before going to sleep using its checker
232 * function [see ZTHR state transition in ZTHR block comment].
233 * Thus, missing the wakeup still yields the expected behavior.
236 zthr_wakeup(zthr_t *t)
238 ASSERT3P(t->zthr_thread, !=, NULL);
240 mutex_enter(&t->zthr_lock);
241 cv_broadcast(&t->zthr_cv);
242 mutex_exit(&t->zthr_lock);
246 * Note: If the zthr is not running (e.g. has been cancelled
247 * already), this is a no-op.
250 zthr_cancel(zthr_t *t)
254 mutex_enter(&t->zthr_lock);
256 /* broadcast in case the zthr is sleeping */
257 cv_broadcast(&t->zthr_cv);
259 t->zthr_cancel = B_TRUE;
260 while (t->zthr_thread != NULL)
261 cv_wait(&t->zthr_cv, &t->zthr_lock);
262 t->zthr_cancel = B_FALSE;
264 mutex_exit(&t->zthr_lock);
270 zthr_resume(zthr_t *t)
272 ASSERT3P(t->zthr_thread, ==, NULL);
274 mutex_enter(&t->zthr_lock);
276 ASSERT3P(&t->zthr_checkfunc, !=, NULL);
277 ASSERT3P(&t->zthr_func, !=, NULL);
278 ASSERT(!t->zthr_cancel);
280 t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
281 0, &p0, TS_RUN, minclsyspri);
283 mutex_exit(&t->zthr_lock);
287 * This function is intended to be used by the zthr itself
288 * to check if another thread has signal it to stop running.
290 * returns TRUE if we are in the middle of trying to cancel
293 * returns FALSE otherwise.
296 zthr_iscancelled(zthr_t *t)
300 ASSERT3P(t->zthr_thread, ==, curthread);
302 mutex_enter(&t->zthr_lock);
303 cancelled = t->zthr_cancel;
304 mutex_exit(&t->zthr_lock);
310 zthr_isrunning(zthr_t *t)
314 mutex_enter(&t->zthr_lock);
315 running = (t->zthr_thread != NULL);
316 mutex_exit(&t->zthr_lock);