xref: /illumos-gate/usr/src/uts/common/fs/zfs/zthr.c (revision 6a316e1f)
1667ec66fSSerapheim Dimitropoulos /*
2667ec66fSSerapheim Dimitropoulos  * CDDL HEADER START
3667ec66fSSerapheim Dimitropoulos  *
4667ec66fSSerapheim Dimitropoulos  * This file and its contents are supplied under the terms of the
5667ec66fSSerapheim Dimitropoulos  * Common Development and Distribution License ("CDDL"), version 1.0.
6667ec66fSSerapheim Dimitropoulos  * You may only use this file in accordance with the terms of version
7667ec66fSSerapheim Dimitropoulos  * 1.0 of the CDDL.
8667ec66fSSerapheim Dimitropoulos  *
9667ec66fSSerapheim Dimitropoulos  * A full copy of the text of the CDDL should have accompanied this
10667ec66fSSerapheim Dimitropoulos  * source. A copy of the CDDL is also available via the Internet at
11667ec66fSSerapheim Dimitropoulos  * http://www.illumos.org/license/CDDL.
12667ec66fSSerapheim Dimitropoulos  *
13667ec66fSSerapheim Dimitropoulos  * CDDL HEADER END
14667ec66fSSerapheim Dimitropoulos  */
15667ec66fSSerapheim Dimitropoulos 
16667ec66fSSerapheim Dimitropoulos /*
17*6a316e1fSSerapheim Dimitropoulos  * Copyright (c) 2017, 2019 by Delphix. All rights reserved.
18667ec66fSSerapheim Dimitropoulos  */
19667ec66fSSerapheim Dimitropoulos 
20667ec66fSSerapheim Dimitropoulos /*
21667ec66fSSerapheim Dimitropoulos  * ZTHR Infrastructure
22667ec66fSSerapheim Dimitropoulos  * ===================
23667ec66fSSerapheim Dimitropoulos  *
24667ec66fSSerapheim Dimitropoulos  * ZTHR threads are used for isolated operations that span multiple txgs
25667ec66fSSerapheim Dimitropoulos  * within a SPA. They generally exist from SPA creation/loading and until
26667ec66fSSerapheim Dimitropoulos  * the SPA is exported/destroyed. The ideal requirements for an operation
27667ec66fSSerapheim Dimitropoulos  * to be modeled with a zthr are the following:
28667ec66fSSerapheim Dimitropoulos  *
29667ec66fSSerapheim Dimitropoulos  * 1] The operation needs to run over multiple txgs.
30667ec66fSSerapheim Dimitropoulos  * 2] There is be a single point of reference in memory or on disk that
31*6a316e1fSSerapheim Dimitropoulos  *    indicates whether the operation should run/is running or has
32667ec66fSSerapheim Dimitropoulos  *    stopped.
33667ec66fSSerapheim Dimitropoulos  *
34667ec66fSSerapheim Dimitropoulos  * If the operation satisfies the above then the following rules guarantee
35667ec66fSSerapheim Dimitropoulos  * a certain level of correctness:
36667ec66fSSerapheim Dimitropoulos  *
37667ec66fSSerapheim Dimitropoulos  * 1] Any thread EXCEPT the zthr changes the work indicator from stopped
38667ec66fSSerapheim Dimitropoulos  *    to running but not the opposite.
39667ec66fSSerapheim Dimitropoulos  * 2] Only the zthr can change the work indicator from running to stopped
40667ec66fSSerapheim Dimitropoulos  *    (e.g. when it is done) but not the opposite.
41667ec66fSSerapheim Dimitropoulos  *
42667ec66fSSerapheim Dimitropoulos  * This way a normal zthr cycle should go like this:
43667ec66fSSerapheim Dimitropoulos  *
44667ec66fSSerapheim Dimitropoulos  * 1] An external thread changes the work indicator from stopped to
45667ec66fSSerapheim Dimitropoulos  *    running and wakes up the zthr.
46667ec66fSSerapheim Dimitropoulos  * 2] The zthr wakes up, checks the indicator and starts working.
47667ec66fSSerapheim Dimitropoulos  * 3] When the zthr is done, it changes the indicator to stopped, allowing
48667ec66fSSerapheim Dimitropoulos  *    a new cycle to start.
49667ec66fSSerapheim Dimitropoulos  *
50de753e34SBrad Lewis  * Besides being awakened by other threads, a zthr can be configured
51de753e34SBrad Lewis  * during creation to wakeup on it's own after a specified interval
52de753e34SBrad Lewis  * [see zthr_create_timer()].
53de753e34SBrad Lewis  *
54*6a316e1fSSerapheim Dimitropoulos  * Note: ZTHR threads are NOT a replacement for generic threads! Please
55*6a316e1fSSerapheim Dimitropoulos  * ensure that they fit your use-case well before using them.
56*6a316e1fSSerapheim Dimitropoulos  *
57667ec66fSSerapheim Dimitropoulos  * == ZTHR creation
58667ec66fSSerapheim Dimitropoulos  *
59667ec66fSSerapheim Dimitropoulos  * Every zthr needs three inputs to start running:
60667ec66fSSerapheim Dimitropoulos  *
61667ec66fSSerapheim Dimitropoulos  * 1] A user-defined checker function (checkfunc) that decides whether
62667ec66fSSerapheim Dimitropoulos  *    the zthr should start working or go to sleep. The function should
63667ec66fSSerapheim Dimitropoulos  *    return TRUE when the zthr needs to work or FALSE to let it sleep,
64667ec66fSSerapheim Dimitropoulos  *    and should adhere to the following signature:
65667ec66fSSerapheim Dimitropoulos  *    boolean_t checkfunc_name(void *args, zthr_t *t);
66667ec66fSSerapheim Dimitropoulos  *
67667ec66fSSerapheim Dimitropoulos  * 2] A user-defined ZTHR function (func) which the zthr executes when
68667ec66fSSerapheim Dimitropoulos  *    it is not sleeping. The function should adhere to the following
69667ec66fSSerapheim Dimitropoulos  *    signature type:
70*6a316e1fSSerapheim Dimitropoulos  *    void func_name(void *args, zthr_t *t);
71667ec66fSSerapheim Dimitropoulos  *
72667ec66fSSerapheim Dimitropoulos  * 3] A void args pointer that will be passed to checkfunc and func
73667ec66fSSerapheim Dimitropoulos  *    implicitly by the infrastructure.
74667ec66fSSerapheim Dimitropoulos  *
75667ec66fSSerapheim Dimitropoulos  * The reason why the above API needs two different functions,
76667ec66fSSerapheim Dimitropoulos  * instead of one that both checks and does the work, has to do with
77*6a316e1fSSerapheim Dimitropoulos  * the zthr's internal state lock (zthr_state_lock) and the allowed
78*6a316e1fSSerapheim Dimitropoulos  * cancellation windows. We want to hold the zthr_state_lock while
79*6a316e1fSSerapheim Dimitropoulos  * running checkfunc but not while running func. This way the zthr
80*6a316e1fSSerapheim Dimitropoulos  * can be cancelled while doing work and not while checking for work.
81667ec66fSSerapheim Dimitropoulos  *
82667ec66fSSerapheim Dimitropoulos  * To start a zthr:
83667ec66fSSerapheim Dimitropoulos  *     zthr_t *zthr_pointer = zthr_create(checkfunc, func, args);
84de753e34SBrad Lewis  * or
85de753e34SBrad Lewis  *     zthr_t *zthr_pointer = zthr_create_timer(checkfunc, func,
86de753e34SBrad Lewis  *         args, max_sleep);
87667ec66fSSerapheim Dimitropoulos  *
88667ec66fSSerapheim Dimitropoulos  * After that you should be able to wakeup, cancel, and resume the
89*6a316e1fSSerapheim Dimitropoulos  * zthr from another thread using the zthr_pointer.
90667ec66fSSerapheim Dimitropoulos  *
91667ec66fSSerapheim Dimitropoulos  * NOTE: ZTHR threads could potentially wake up spuriously and the
92667ec66fSSerapheim Dimitropoulos  * user should take this into account when writing a checkfunc.
93667ec66fSSerapheim Dimitropoulos  * [see ZTHR state transitions]
94667ec66fSSerapheim Dimitropoulos  *
95667ec66fSSerapheim Dimitropoulos  * == ZTHR cancellation
96667ec66fSSerapheim Dimitropoulos  *
97667ec66fSSerapheim Dimitropoulos  * ZTHR threads must be cancelled when their SPA is being exported
98667ec66fSSerapheim Dimitropoulos  * or when they need to be paused so they don't interfere with other
99667ec66fSSerapheim Dimitropoulos  * operations.
100667ec66fSSerapheim Dimitropoulos  *
101667ec66fSSerapheim Dimitropoulos  * To cancel a zthr:
102667ec66fSSerapheim Dimitropoulos  *     zthr_cancel(zthr_pointer);
103667ec66fSSerapheim Dimitropoulos  *
104667ec66fSSerapheim Dimitropoulos  * To resume it:
105667ec66fSSerapheim Dimitropoulos  *     zthr_resume(zthr_pointer);
106667ec66fSSerapheim Dimitropoulos  *
107667ec66fSSerapheim Dimitropoulos  * A zthr will implicitly check if it has received a cancellation
108*6a316e1fSSerapheim Dimitropoulos  * signal every time func returns and every time it wakes up [see
109*6a316e1fSSerapheim Dimitropoulos  * ZTHR state transitions below].
110667ec66fSSerapheim Dimitropoulos  *
111667ec66fSSerapheim Dimitropoulos  * At times, waiting for the zthr's func to finish its job may take
112667ec66fSSerapheim Dimitropoulos  * time. This may be very time-consuming for some operations that
113667ec66fSSerapheim Dimitropoulos  * need to cancel the SPA's zthrs (e.g spa_export). For this scenario
114667ec66fSSerapheim Dimitropoulos  * the user can explicitly make their ZTHR function aware of incoming
115667ec66fSSerapheim Dimitropoulos  * cancellation signals using zthr_iscancelled(). A common pattern for
116667ec66fSSerapheim Dimitropoulos  * that looks like this:
117667ec66fSSerapheim Dimitropoulos  *
118667ec66fSSerapheim Dimitropoulos  * int
119667ec66fSSerapheim Dimitropoulos  * func_name(void *args, zthr_t *t)
120667ec66fSSerapheim Dimitropoulos  * {
121667ec66fSSerapheim Dimitropoulos  *     ... <unpack args> ...
122667ec66fSSerapheim Dimitropoulos  *     while (!work_done && !zthr_iscancelled(t)) {
123667ec66fSSerapheim Dimitropoulos  *         ... <do more work> ...
124667ec66fSSerapheim Dimitropoulos  *     }
125667ec66fSSerapheim Dimitropoulos  * }
126667ec66fSSerapheim Dimitropoulos  *
127667ec66fSSerapheim Dimitropoulos  * == ZTHR cleanup
128667ec66fSSerapheim Dimitropoulos  *
129667ec66fSSerapheim Dimitropoulos  * Cancelling a zthr doesn't clean up its metadata (internal locks,
130667ec66fSSerapheim Dimitropoulos  * function pointers to func and checkfunc, etc..). This is because
131667ec66fSSerapheim Dimitropoulos  * we want to keep them around in case we want to resume the execution
132667ec66fSSerapheim Dimitropoulos  * of the zthr later. Similarly for zthrs that exit themselves.
133667ec66fSSerapheim Dimitropoulos  *
134667ec66fSSerapheim Dimitropoulos  * To completely cleanup a zthr, cancel it first to ensure that it
135667ec66fSSerapheim Dimitropoulos  * is not running and then use zthr_destroy().
136667ec66fSSerapheim Dimitropoulos  *
137667ec66fSSerapheim Dimitropoulos  * == ZTHR state transitions
138667ec66fSSerapheim Dimitropoulos  *
139667ec66fSSerapheim Dimitropoulos  *    zthr creation
140667ec66fSSerapheim Dimitropoulos  *      +
141667ec66fSSerapheim Dimitropoulos  *      |
142667ec66fSSerapheim Dimitropoulos  *      |      woke up
143667ec66fSSerapheim Dimitropoulos  *      |   +--------------+ sleep
144667ec66fSSerapheim Dimitropoulos  *      |   |                  ^
145667ec66fSSerapheim Dimitropoulos  *      |   |                  |
146667ec66fSSerapheim Dimitropoulos  *      |   |                  | FALSE
147667ec66fSSerapheim Dimitropoulos  *      |   |                  |
148667ec66fSSerapheim Dimitropoulos  *      v   v     FALSE        +
149667ec66fSSerapheim Dimitropoulos  *   cancelled? +---------> checkfunc?
150667ec66fSSerapheim Dimitropoulos  *      +   ^                  +
151667ec66fSSerapheim Dimitropoulos  *      |   |                  |
152667ec66fSSerapheim Dimitropoulos  *      |   |                  | TRUE
153667ec66fSSerapheim Dimitropoulos  *      |   |                  |
154667ec66fSSerapheim Dimitropoulos  *      |   |  func returned   v
155667ec66fSSerapheim Dimitropoulos  *      |   +---------------+ func
156667ec66fSSerapheim Dimitropoulos  *      |
157667ec66fSSerapheim Dimitropoulos  *      | TRUE
158667ec66fSSerapheim Dimitropoulos  *      |
159667ec66fSSerapheim Dimitropoulos  *      v
160667ec66fSSerapheim Dimitropoulos  *   zthr stopped running
161667ec66fSSerapheim Dimitropoulos  *
162*6a316e1fSSerapheim Dimitropoulos  * == Implementation of ZTHR requests
163*6a316e1fSSerapheim Dimitropoulos  *
164*6a316e1fSSerapheim Dimitropoulos  * ZTHR wakeup, cancel, and resume are requests on a zthr to
165*6a316e1fSSerapheim Dimitropoulos  * change its internal state. Requests on a zthr are serialized
166*6a316e1fSSerapheim Dimitropoulos  * using the zthr_request_lock, while changes in its internal
167*6a316e1fSSerapheim Dimitropoulos  * state are protected by the zthr_state_lock. A request will
168*6a316e1fSSerapheim Dimitropoulos  * first acquire the zthr_request_lock and then immediately
169*6a316e1fSSerapheim Dimitropoulos  * acquire the zthr_state_lock. We do this so that incoming
170*6a316e1fSSerapheim Dimitropoulos  * requests are serialized using the request lock, while still
171*6a316e1fSSerapheim Dimitropoulos  * allowing us to use the state lock for thread communication
172*6a316e1fSSerapheim Dimitropoulos  * via zthr_cv.
173667ec66fSSerapheim Dimitropoulos  */
174667ec66fSSerapheim Dimitropoulos 
175667ec66fSSerapheim Dimitropoulos #include <sys/zfs_context.h>
176667ec66fSSerapheim Dimitropoulos #include <sys/zthr.h>
177667ec66fSSerapheim Dimitropoulos 
178*6a316e1fSSerapheim Dimitropoulos struct zthr {
179*6a316e1fSSerapheim Dimitropoulos 	/* running thread doing the work */
180*6a316e1fSSerapheim Dimitropoulos 	kthread_t	*zthr_thread;
181*6a316e1fSSerapheim Dimitropoulos 
182*6a316e1fSSerapheim Dimitropoulos 	/* lock protecting internal data & invariants */
183*6a316e1fSSerapheim Dimitropoulos 	kmutex_t	zthr_state_lock;
184*6a316e1fSSerapheim Dimitropoulos 
185*6a316e1fSSerapheim Dimitropoulos 	/* mutex that serializes external requests */
186*6a316e1fSSerapheim Dimitropoulos 	kmutex_t	zthr_request_lock;
187*6a316e1fSSerapheim Dimitropoulos 
188*6a316e1fSSerapheim Dimitropoulos 	/* notification mechanism for requests */
189*6a316e1fSSerapheim Dimitropoulos 	kcondvar_t	zthr_cv;
190*6a316e1fSSerapheim Dimitropoulos 
191*6a316e1fSSerapheim Dimitropoulos 	/* flag set to true if we are canceling the zthr */
192*6a316e1fSSerapheim Dimitropoulos 	boolean_t	zthr_cancel;
193*6a316e1fSSerapheim Dimitropoulos 
194*6a316e1fSSerapheim Dimitropoulos 	/*
195*6a316e1fSSerapheim Dimitropoulos 	 * maximum amount of time that the zthr is spent sleeping;
196*6a316e1fSSerapheim Dimitropoulos 	 * if this is 0, the thread doesn't wake up until it gets
197*6a316e1fSSerapheim Dimitropoulos 	 * signaled.
198*6a316e1fSSerapheim Dimitropoulos 	 */
199*6a316e1fSSerapheim Dimitropoulos 	hrtime_t	zthr_wait_time;
200*6a316e1fSSerapheim Dimitropoulos 
201*6a316e1fSSerapheim Dimitropoulos 	/* consumer-provided callbacks & data */
202*6a316e1fSSerapheim Dimitropoulos 	zthr_checkfunc_t	*zthr_checkfunc;
203*6a316e1fSSerapheim Dimitropoulos 	zthr_func_t	*zthr_func;
204*6a316e1fSSerapheim Dimitropoulos 	void		*zthr_arg;
205*6a316e1fSSerapheim Dimitropoulos };
206667ec66fSSerapheim Dimitropoulos 
207667ec66fSSerapheim Dimitropoulos static void
zthr_procedure(void * arg)208667ec66fSSerapheim Dimitropoulos zthr_procedure(void *arg)
209667ec66fSSerapheim Dimitropoulos {
210667ec66fSSerapheim Dimitropoulos 	zthr_t *t = arg;
211667ec66fSSerapheim Dimitropoulos 
212*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
213*6a316e1fSSerapheim Dimitropoulos 	ASSERT3P(t->zthr_thread, ==, curthread);
214*6a316e1fSSerapheim Dimitropoulos 
215667ec66fSSerapheim Dimitropoulos 	while (!t->zthr_cancel) {
216667ec66fSSerapheim Dimitropoulos 		if (t->zthr_checkfunc(t->zthr_arg, t)) {
217*6a316e1fSSerapheim Dimitropoulos 			mutex_exit(&t->zthr_state_lock);
218*6a316e1fSSerapheim Dimitropoulos 			t->zthr_func(t->zthr_arg, t);
219*6a316e1fSSerapheim Dimitropoulos 			mutex_enter(&t->zthr_state_lock);
220667ec66fSSerapheim Dimitropoulos 		} else {
221667ec66fSSerapheim Dimitropoulos 			/* go to sleep */
222de753e34SBrad Lewis 			if (t->zthr_wait_time == 0) {
223*6a316e1fSSerapheim Dimitropoulos 				cv_wait(&t->zthr_cv, &t->zthr_state_lock);
224de753e34SBrad Lewis 			} else {
225de753e34SBrad Lewis 				(void) cv_timedwait_hires(&t->zthr_cv,
226*6a316e1fSSerapheim Dimitropoulos 				    &t->zthr_state_lock, t->zthr_wait_time,
227de753e34SBrad Lewis 				    MSEC2NSEC(1), 0);
228de753e34SBrad Lewis 			}
229667ec66fSSerapheim Dimitropoulos 		}
230667ec66fSSerapheim Dimitropoulos 	}
231667ec66fSSerapheim Dimitropoulos 
232*6a316e1fSSerapheim Dimitropoulos 	/*
233*6a316e1fSSerapheim Dimitropoulos 	 * Clear out the kernel thread metadata and notify the
234*6a316e1fSSerapheim Dimitropoulos 	 * zthr_cancel() thread that we've stopped running.
235*6a316e1fSSerapheim Dimitropoulos 	 */
236*6a316e1fSSerapheim Dimitropoulos 	t->zthr_thread = NULL;
237*6a316e1fSSerapheim Dimitropoulos 	t->zthr_cancel = B_FALSE;
238*6a316e1fSSerapheim Dimitropoulos 	cv_broadcast(&t->zthr_cv);
239*6a316e1fSSerapheim Dimitropoulos 
240*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
241*6a316e1fSSerapheim Dimitropoulos 	thread_exit();
242667ec66fSSerapheim Dimitropoulos }
243667ec66fSSerapheim Dimitropoulos 
244667ec66fSSerapheim Dimitropoulos zthr_t *
zthr_create(zthr_checkfunc_t * checkfunc,zthr_func_t * func,void * arg)245667ec66fSSerapheim Dimitropoulos zthr_create(zthr_checkfunc_t *checkfunc, zthr_func_t *func, void *arg)
246de753e34SBrad Lewis {
247de753e34SBrad Lewis 	return (zthr_create_timer(checkfunc, func, arg, (hrtime_t)0));
248de753e34SBrad Lewis }
249de753e34SBrad Lewis 
250de753e34SBrad Lewis /*
251de753e34SBrad Lewis  * Create a zthr with specified maximum sleep time.  If the time
252de753e34SBrad Lewis  * in sleeping state exceeds max_sleep, a wakeup(do the check and
253de753e34SBrad Lewis  * start working if required) will be triggered.
254de753e34SBrad Lewis  */
255de753e34SBrad Lewis zthr_t *
zthr_create_timer(zthr_checkfunc_t * checkfunc,zthr_func_t * func,void * arg,hrtime_t max_sleep)256de753e34SBrad Lewis zthr_create_timer(zthr_checkfunc_t *checkfunc, zthr_func_t *func,
257de753e34SBrad Lewis     void *arg, hrtime_t max_sleep)
258667ec66fSSerapheim Dimitropoulos {
259667ec66fSSerapheim Dimitropoulos 	zthr_t *t = kmem_zalloc(sizeof (*t), KM_SLEEP);
260*6a316e1fSSerapheim Dimitropoulos 	mutex_init(&t->zthr_state_lock, NULL, MUTEX_DEFAULT, NULL);
261*6a316e1fSSerapheim Dimitropoulos 	mutex_init(&t->zthr_request_lock, NULL, MUTEX_DEFAULT, NULL);
262667ec66fSSerapheim Dimitropoulos 	cv_init(&t->zthr_cv, NULL, CV_DEFAULT, NULL);
263667ec66fSSerapheim Dimitropoulos 
264*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
265667ec66fSSerapheim Dimitropoulos 	t->zthr_checkfunc = checkfunc;
266667ec66fSSerapheim Dimitropoulos 	t->zthr_func = func;
267667ec66fSSerapheim Dimitropoulos 	t->zthr_arg = arg;
268de753e34SBrad Lewis 	t->zthr_wait_time = max_sleep;
269667ec66fSSerapheim Dimitropoulos 
270667ec66fSSerapheim Dimitropoulos 	t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
271667ec66fSSerapheim Dimitropoulos 	    0, &p0, TS_RUN, minclsyspri);
272*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
273667ec66fSSerapheim Dimitropoulos 
274667ec66fSSerapheim Dimitropoulos 	return (t);
275667ec66fSSerapheim Dimitropoulos }
276667ec66fSSerapheim Dimitropoulos 
277667ec66fSSerapheim Dimitropoulos void
zthr_destroy(zthr_t * t)278667ec66fSSerapheim Dimitropoulos zthr_destroy(zthr_t *t)
279667ec66fSSerapheim Dimitropoulos {
280*6a316e1fSSerapheim Dimitropoulos 	ASSERT(!MUTEX_HELD(&t->zthr_state_lock));
281*6a316e1fSSerapheim Dimitropoulos 	ASSERT(!MUTEX_HELD(&t->zthr_request_lock));
282667ec66fSSerapheim Dimitropoulos 	VERIFY3P(t->zthr_thread, ==, NULL);
283*6a316e1fSSerapheim Dimitropoulos 	mutex_destroy(&t->zthr_request_lock);
284*6a316e1fSSerapheim Dimitropoulos 	mutex_destroy(&t->zthr_state_lock);
285667ec66fSSerapheim Dimitropoulos 	cv_destroy(&t->zthr_cv);
286667ec66fSSerapheim Dimitropoulos 	kmem_free(t, sizeof (*t));
287667ec66fSSerapheim Dimitropoulos }
288667ec66fSSerapheim Dimitropoulos 
289667ec66fSSerapheim Dimitropoulos /*
290*6a316e1fSSerapheim Dimitropoulos  * Wake up the zthr if it is sleeping. If the thread has been
291*6a316e1fSSerapheim Dimitropoulos  * cancelled that does nothing.
292667ec66fSSerapheim Dimitropoulos  */
293667ec66fSSerapheim Dimitropoulos void
zthr_wakeup(zthr_t * t)294667ec66fSSerapheim Dimitropoulos zthr_wakeup(zthr_t *t)
295667ec66fSSerapheim Dimitropoulos {
296*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_request_lock);
297*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
298*6a316e1fSSerapheim Dimitropoulos 
299*6a316e1fSSerapheim Dimitropoulos 	/*
300*6a316e1fSSerapheim Dimitropoulos 	 * There are 4 states that we can find the zthr when issuing
301*6a316e1fSSerapheim Dimitropoulos 	 * this broadcast:
302*6a316e1fSSerapheim Dimitropoulos 	 *
303*6a316e1fSSerapheim Dimitropoulos 	 * [1] The common case of the thread being asleep, at which
304*6a316e1fSSerapheim Dimitropoulos 	 *     point the broadcast will wake it up.
305*6a316e1fSSerapheim Dimitropoulos 	 * [2] The thread has been cancelled. Waking up a cancelled
306*6a316e1fSSerapheim Dimitropoulos 	 *     thread is a no-op. Any work that is still left to be
307*6a316e1fSSerapheim Dimitropoulos 	 *     done should be handled the next time the thread is
308*6a316e1fSSerapheim Dimitropoulos 	 *     resumed.
309*6a316e1fSSerapheim Dimitropoulos 	 * [3] The thread is doing work and is already up, so this
310*6a316e1fSSerapheim Dimitropoulos 	 *     is basically a no-op.
311*6a316e1fSSerapheim Dimitropoulos 	 * [4] The thread was just created/resumed, in which case the
312*6a316e1fSSerapheim Dimitropoulos 	 *     behavior is similar to [3].
313*6a316e1fSSerapheim Dimitropoulos 	 */
314667ec66fSSerapheim Dimitropoulos 	cv_broadcast(&t->zthr_cv);
315*6a316e1fSSerapheim Dimitropoulos 
316*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
317*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_request_lock);
318667ec66fSSerapheim Dimitropoulos }
319667ec66fSSerapheim Dimitropoulos 
320667ec66fSSerapheim Dimitropoulos /*
321*6a316e1fSSerapheim Dimitropoulos  * Sends a cancel request to the zthr and blocks until the zthr is
322*6a316e1fSSerapheim Dimitropoulos  * cancelled. If the zthr is not running (e.g. has been cancelled
323667ec66fSSerapheim Dimitropoulos  * already), this is a no-op.
324667ec66fSSerapheim Dimitropoulos  */
325*6a316e1fSSerapheim Dimitropoulos void
zthr_cancel(zthr_t * t)326667ec66fSSerapheim Dimitropoulos zthr_cancel(zthr_t *t)
327667ec66fSSerapheim Dimitropoulos {
328*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_request_lock);
329*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
330667ec66fSSerapheim Dimitropoulos 
331*6a316e1fSSerapheim Dimitropoulos 	/*
332*6a316e1fSSerapheim Dimitropoulos 	 * Since we are holding the zthr_state_lock at this point
333*6a316e1fSSerapheim Dimitropoulos 	 * we can find the state in one of the following 4 states:
334*6a316e1fSSerapheim Dimitropoulos 	 *
335*6a316e1fSSerapheim Dimitropoulos 	 * [1] The thread has already been cancelled, therefore
336*6a316e1fSSerapheim Dimitropoulos 	 *     there is nothing for us to do.
337*6a316e1fSSerapheim Dimitropoulos 	 * [2] The thread is sleeping, so we broadcast the CV first
338*6a316e1fSSerapheim Dimitropoulos 	 *     to wake it up and then we set the flag and we are
339*6a316e1fSSerapheim Dimitropoulos 	 *     waiting for it to exit.
340*6a316e1fSSerapheim Dimitropoulos 	 * [3] The thread is doing work, in which case we just set
341*6a316e1fSSerapheim Dimitropoulos 	 *     the flag and wait for it to finish.
342*6a316e1fSSerapheim Dimitropoulos 	 * [4] The thread was just created/resumed, in which case
343*6a316e1fSSerapheim Dimitropoulos 	 *     the behavior is similar to [3].
344*6a316e1fSSerapheim Dimitropoulos 	 *
345*6a316e1fSSerapheim Dimitropoulos 	 * Since requests are serialized, by the time that we get
346*6a316e1fSSerapheim Dimitropoulos 	 * control back we expect that the zthr is cancelled and
347*6a316e1fSSerapheim Dimitropoulos 	 * not running anymore.
348*6a316e1fSSerapheim Dimitropoulos 	 */
349*6a316e1fSSerapheim Dimitropoulos 	if (t->zthr_thread != NULL) {
350*6a316e1fSSerapheim Dimitropoulos 		t->zthr_cancel = B_TRUE;
351667ec66fSSerapheim Dimitropoulos 
352*6a316e1fSSerapheim Dimitropoulos 		/* broadcast in case the zthr is sleeping */
353*6a316e1fSSerapheim Dimitropoulos 		cv_broadcast(&t->zthr_cv);
354667ec66fSSerapheim Dimitropoulos 
355*6a316e1fSSerapheim Dimitropoulos 		while (t->zthr_thread != NULL)
356*6a316e1fSSerapheim Dimitropoulos 			cv_wait(&t->zthr_cv, &t->zthr_state_lock);
357667ec66fSSerapheim Dimitropoulos 
358*6a316e1fSSerapheim Dimitropoulos 		ASSERT(!t->zthr_cancel);
359*6a316e1fSSerapheim Dimitropoulos 	}
360*6a316e1fSSerapheim Dimitropoulos 
361*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
362*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_request_lock);
363667ec66fSSerapheim Dimitropoulos }
364667ec66fSSerapheim Dimitropoulos 
365*6a316e1fSSerapheim Dimitropoulos /*
366*6a316e1fSSerapheim Dimitropoulos  * Sends a resume request to the supplied zthr. If the zthr is
367*6a316e1fSSerapheim Dimitropoulos  * already running this is a no-op.
368*6a316e1fSSerapheim Dimitropoulos  */
369667ec66fSSerapheim Dimitropoulos void
zthr_resume(zthr_t * t)370667ec66fSSerapheim Dimitropoulos zthr_resume(zthr_t *t)
371667ec66fSSerapheim Dimitropoulos {
372*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_request_lock);
373*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
374667ec66fSSerapheim Dimitropoulos 
375667ec66fSSerapheim Dimitropoulos 	ASSERT3P(&t->zthr_checkfunc, !=, NULL);
376667ec66fSSerapheim Dimitropoulos 	ASSERT3P(&t->zthr_func, !=, NULL);
377667ec66fSSerapheim Dimitropoulos 	ASSERT(!t->zthr_cancel);
378667ec66fSSerapheim Dimitropoulos 
379*6a316e1fSSerapheim Dimitropoulos 	/*
380*6a316e1fSSerapheim Dimitropoulos 	 * There are 4 states that we find the zthr in at this point
381*6a316e1fSSerapheim Dimitropoulos 	 * given the locks that we hold:
382*6a316e1fSSerapheim Dimitropoulos 	 *
383*6a316e1fSSerapheim Dimitropoulos 	 * [1] The zthr was cancelled, so we spawn a new thread for
384*6a316e1fSSerapheim Dimitropoulos 	 *     the zthr (common case).
385*6a316e1fSSerapheim Dimitropoulos 	 * [2] The zthr is running at which point this is a no-op.
386*6a316e1fSSerapheim Dimitropoulos 	 * [3] The zthr is sleeping at which point this is a no-op.
387*6a316e1fSSerapheim Dimitropoulos 	 * [4] The zthr was just spawned at which point this is a
388*6a316e1fSSerapheim Dimitropoulos 	 *     no-op.
389*6a316e1fSSerapheim Dimitropoulos 	 */
390*6a316e1fSSerapheim Dimitropoulos 	if (t->zthr_thread == NULL) {
391*6a316e1fSSerapheim Dimitropoulos 		t->zthr_thread = thread_create(NULL, 0, zthr_procedure, t,
392*6a316e1fSSerapheim Dimitropoulos 		    0, &p0, TS_RUN, minclsyspri);
393*6a316e1fSSerapheim Dimitropoulos 	}
394667ec66fSSerapheim Dimitropoulos 
395*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
396*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_request_lock);
397667ec66fSSerapheim Dimitropoulos }
398667ec66fSSerapheim Dimitropoulos 
399667ec66fSSerapheim Dimitropoulos /*
400667ec66fSSerapheim Dimitropoulos  * This function is intended to be used by the zthr itself
401*6a316e1fSSerapheim Dimitropoulos  * (specifically the zthr_func callback provided) to check
402*6a316e1fSSerapheim Dimitropoulos  * if another thread has signaled it to stop running before
403*6a316e1fSSerapheim Dimitropoulos  * doing some expensive operation.
404667ec66fSSerapheim Dimitropoulos  *
405667ec66fSSerapheim Dimitropoulos  * returns TRUE if we are in the middle of trying to cancel
406667ec66fSSerapheim Dimitropoulos  *     this thread.
407667ec66fSSerapheim Dimitropoulos  *
408667ec66fSSerapheim Dimitropoulos  * returns FALSE otherwise.
409667ec66fSSerapheim Dimitropoulos  */
410667ec66fSSerapheim Dimitropoulos boolean_t
zthr_iscancelled(zthr_t * t)411667ec66fSSerapheim Dimitropoulos zthr_iscancelled(zthr_t *t)
412667ec66fSSerapheim Dimitropoulos {
413667ec66fSSerapheim Dimitropoulos 	ASSERT3P(t->zthr_thread, ==, curthread);
414667ec66fSSerapheim Dimitropoulos 
415*6a316e1fSSerapheim Dimitropoulos 	/*
416*6a316e1fSSerapheim Dimitropoulos 	 * The majority of the functions here grab zthr_request_lock
417*6a316e1fSSerapheim Dimitropoulos 	 * first and then zthr_state_lock. This function only grabs
418*6a316e1fSSerapheim Dimitropoulos 	 * the zthr_state_lock. That is because this function should
419*6a316e1fSSerapheim Dimitropoulos 	 * only be called from the zthr_func to check if someone has
420*6a316e1fSSerapheim Dimitropoulos 	 * issued a zthr_cancel() on the thread. If there is a zthr_cancel()
421*6a316e1fSSerapheim Dimitropoulos 	 * happening concurrently, attempting to grab the request lock
422*6a316e1fSSerapheim Dimitropoulos 	 * here would result in a deadlock.
423*6a316e1fSSerapheim Dimitropoulos 	 *
424*6a316e1fSSerapheim Dimitropoulos 	 * By grabbing only the zthr_state_lock this function is allowed
425*6a316e1fSSerapheim Dimitropoulos 	 * to run concurrently with a zthr_cancel() request.
426*6a316e1fSSerapheim Dimitropoulos 	 */
427*6a316e1fSSerapheim Dimitropoulos 	mutex_enter(&t->zthr_state_lock);
428*6a316e1fSSerapheim Dimitropoulos 	boolean_t cancelled = t->zthr_cancel;
429*6a316e1fSSerapheim Dimitropoulos 	mutex_exit(&t->zthr_state_lock);
430667ec66fSSerapheim Dimitropoulos 	return (cancelled);
431667ec66fSSerapheim Dimitropoulos }
432