]>
git.proxmox.com Git - mirror_zfs.git/blob - module/zfs/zthr.c
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.
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()].
56 * Every zthr needs three inputs to start running:
58 * 1] A user-defined checker function (checkfunc) that decides whether
59 * the zthr should start working or go to sleep. The function should
60 * return TRUE when the zthr needs to work or FALSE to let it sleep,
61 * and should adhere to the following signature:
62 * boolean_t checkfunc_name(void *args, zthr_t *t);
64 * 2] A user-defined ZTHR function (func) which the zthr executes when
65 * it is not sleeping. The function should adhere to the following
67 * int func_name(void *args, zthr_t *t);
69 * 3] A void args pointer that will be passed to checkfunc and func
70 * implicitly by the infrastructure.
72 * The reason why the above API needs two different functions,
73 * instead of one that both checks and does the work, has to do with
74 * the zthr's internal lock (zthr_lock) and the allowed cancellation
75 * windows. We want to hold the zthr_lock while running checkfunc
76 * but not while running func. This way the zthr can be cancelled
77 * while doing work and not while checking for work.
80 * zthr_t *zthr_pointer = zthr_create(checkfunc, func, args);
82 * zthr_t *zthr_pointer = zthr_create_timer(checkfunc, func,
85 * After that you should be able to wakeup, cancel, and resume the
86 * zthr from another thread using zthr_pointer.
88 * NOTE: ZTHR threads could potentially wake up spuriously and the
89 * user should take this into account when writing a checkfunc.
90 * [see ZTHR state transitions]
92 * == ZTHR cancellation
94 * ZTHR threads must be cancelled when their SPA is being exported
95 * or when they need to be paused so they don't interfere with other
99 * zthr_cancel(zthr_pointer);
102 * zthr_resume(zthr_pointer);
104 * A zthr will implicitly check if it has received a cancellation
105 * signal every time func returns and everytime it wakes up [see ZTHR
106 * state transitions below].
108 * At times, waiting for the zthr's func to finish its job may take
109 * time. This may be very time-consuming for some operations that
110 * need to cancel the SPA's zthrs (e.g spa_export). For this scenario
111 * the user can explicitly make their ZTHR function aware of incoming
112 * cancellation signals using zthr_iscancelled(). A common pattern for
113 * that looks like this:
116 * func_name(void *args, zthr_t *t)
118 * ... <unpack args> ...
119 * while (!work_done && !zthr_iscancelled(t)) {
120 * ... <do more work> ...
127 * For the rare cases where the zthr wants to stop running voluntarily
128 * while running its ZTHR function (func), we provide zthr_exit().
129 * When a zthr has voluntarily stopped running, it can be resumed with
130 * zthr_resume(), just like it would if it was cancelled by some other
135 * Cancelling a zthr doesn't clean up its metadata (internal locks,
136 * function pointers to func and checkfunc, etc..). This is because
137 * we want to keep them around in case we want to resume the execution
138 * of the zthr later. Similarly for zthrs that exit themselves.
140 * To completely cleanup a zthr, cancel it first to ensure that it
141 * is not running and then use zthr_destroy().
143 * == ZTHR state transitions
149 * | +--------------+ sleep
155 * cancelled? +---------> checkfunc?
160 * | | func returned v
161 * | +---------------+ func
166 * zthr stopped running
170 #include <sys/zfs_context.h>
171 #include <sys/zthr.h>
174 zthr_exit(zthr_t
*t
, int rc
)
176 ASSERT3P(t
->zthr_thread
, ==, curthread
);
177 mutex_enter(&t
->zthr_lock
);
178 t
->zthr_thread
= NULL
;
180 cv_broadcast(&t
->zthr_cv
);
181 mutex_exit(&t
->zthr_lock
);
186 zthr_procedure(void *arg
)
191 mutex_enter(&t
->zthr_lock
);
192 while (!t
->zthr_cancel
) {
193 if (t
->zthr_checkfunc(t
->zthr_arg
, t
)) {
194 mutex_exit(&t
->zthr_lock
);
195 rc
= t
->zthr_func(t
->zthr_arg
, t
);
196 mutex_enter(&t
->zthr_lock
);
199 if (t
->zthr_wait_time
== 0) {
200 cv_wait_sig(&t
->zthr_cv
, &t
->zthr_lock
);
202 (void) cv_timedwait_sig_hires(&t
->zthr_cv
,
203 &t
->zthr_lock
, t
->zthr_wait_time
,
208 mutex_exit(&t
->zthr_lock
);
214 zthr_create(zthr_checkfunc_t
*checkfunc
, zthr_func_t
*func
, void *arg
)
216 return (zthr_create_timer(checkfunc
, func
, arg
, (hrtime_t
)0));
220 * Create a zthr with specified maximum sleep time. If the time
221 * in sleeping state exceeds max_sleep, a wakeup(do the check and
222 * start working if required) will be triggered.
225 zthr_create_timer(zthr_checkfunc_t
*checkfunc
, zthr_func_t
*func
,
226 void *arg
, hrtime_t max_sleep
)
228 zthr_t
*t
= kmem_zalloc(sizeof (*t
), KM_SLEEP
);
229 mutex_init(&t
->zthr_lock
, NULL
, MUTEX_DEFAULT
, NULL
);
230 cv_init(&t
->zthr_cv
, NULL
, CV_DEFAULT
, NULL
);
232 mutex_enter(&t
->zthr_lock
);
233 t
->zthr_checkfunc
= checkfunc
;
236 t
->zthr_wait_time
= max_sleep
;
238 t
->zthr_thread
= thread_create(NULL
, 0, zthr_procedure
, t
,
239 0, &p0
, TS_RUN
, minclsyspri
);
240 mutex_exit(&t
->zthr_lock
);
246 zthr_destroy(zthr_t
*t
)
248 VERIFY3P(t
->zthr_thread
, ==, NULL
);
249 mutex_destroy(&t
->zthr_lock
);
250 cv_destroy(&t
->zthr_cv
);
251 kmem_free(t
, sizeof (*t
));
255 * Note: If the zthr is not sleeping and misses the wakeup
256 * (e.g it is running its ZTHR function), it will check if
257 * there is work to do before going to sleep using its checker
258 * function [see ZTHR state transition in ZTHR block comment].
259 * Thus, missing the wakeup still yields the expected behavior.
262 zthr_wakeup(zthr_t
*t
)
264 mutex_enter(&t
->zthr_lock
);
265 cv_broadcast(&t
->zthr_cv
);
266 mutex_exit(&t
->zthr_lock
);
270 * Note: If the zthr is not running (e.g. has been cancelled
271 * already), this is a no-op.
274 zthr_cancel(zthr_t
*t
)
278 mutex_enter(&t
->zthr_lock
);
280 /* broadcast in case the zthr is sleeping */
281 cv_broadcast(&t
->zthr_cv
);
283 t
->zthr_cancel
= B_TRUE
;
284 while (t
->zthr_thread
!= NULL
)
285 cv_wait(&t
->zthr_cv
, &t
->zthr_lock
);
286 t
->zthr_cancel
= B_FALSE
;
288 mutex_exit(&t
->zthr_lock
);
294 zthr_resume(zthr_t
*t
)
296 ASSERT3P(t
->zthr_thread
, ==, NULL
);
298 mutex_enter(&t
->zthr_lock
);
300 ASSERT3P(&t
->zthr_checkfunc
, !=, NULL
);
301 ASSERT3P(&t
->zthr_func
, !=, NULL
);
302 ASSERT(!t
->zthr_cancel
);
304 t
->zthr_thread
= thread_create(NULL
, 0, zthr_procedure
, t
,
305 0, &p0
, TS_RUN
, minclsyspri
);
307 mutex_exit(&t
->zthr_lock
);
311 * This function is intended to be used by the zthr itself
312 * to check if another thread has signal it to stop running.
314 * returns TRUE if we are in the middle of trying to cancel
317 * returns FALSE otherwise.
320 zthr_iscancelled(zthr_t
*t
)
324 ASSERT3P(t
->zthr_thread
, ==, curthread
);
326 mutex_enter(&t
->zthr_lock
);
327 cancelled
= t
->zthr_cancel
;
328 mutex_exit(&t
->zthr_lock
);
334 zthr_isrunning(zthr_t
*t
)
338 mutex_enter(&t
->zthr_lock
);
339 running
= (t
->zthr_thread
!= NULL
);
340 mutex_exit(&t
->zthr_lock
);