1/*
2 * Copyright (c) 1993-1995, 1999-2008 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29/*!
30 @header thread_call.h
31 @discussion Facilities for executing work asynchronously.
32 */
33
34#ifndef _KERN_THREAD_CALL_H_
35#define _KERN_THREAD_CALL_H_
36
37#include <mach/mach_types.h>
38
39#include <kern/clock.h>
40
41#include <sys/cdefs.h>
42
43struct thread_call;
44typedef struct thread_call *thread_call_t;
45
46typedef void *thread_call_param_t;
47typedef void (*thread_call_func_t)(
48					thread_call_param_t	param0,
49					thread_call_param_t	param1);
50/*!
51 @enum thread_call_priority_t
52 @discussion Thread call priorities should not be assumed to have any specific
53 numerical value; they should be interpreted as importances or roles for work
54 items, priorities for which will be reasonably managed by the subsystem.
55 @constant THREAD_CALL_PRIORITY_HIGH Importance above everything but realtime.
56 Thread calls allocated with this priority execute at extremely high priority,
57 above everything but realtime threads.  They are generally executed  in serial.
58 Though they may execute concurrently under some circumstances, no fan-out is implied.
59 These work items should do very small amounts of work or risk disrupting system
60 responsiveness.
61 @constant THREAD_CALL_PRIORITY_KERNEL Importance similar to that of normal kernel
62 threads.
63 @constant THREAD_CALL_PRIORITY_USER Importance similar to that of normal user threads.
64 @constant THREAD_CALL_PRIORITY_LOW Very low importance.
65 */
66typedef enum {
67	THREAD_CALL_PRIORITY_HIGH 	= 0,
68	THREAD_CALL_PRIORITY_KERNEL 	= 1,
69	THREAD_CALL_PRIORITY_USER 	= 2,
70	THREAD_CALL_PRIORITY_LOW 	= 3
71} thread_call_priority_t;
72
73__BEGIN_DECLS
74
75/*!
76 @function thread_call_enter
77 @abstract Submit a thread call work item for immediate execution.
78 @discussion If the work item is already scheduled for delayed execution, and it has
79 not yet begun to run, that delayed invocation will be cancelled.  Note that if a
80 thread call is rescheduled from its own callback, then multiple invocations of the
81 callback may be in flight at the same time.
82 @result TRUE if the call was already pending for either delayed or immediate
83 execution, FALSE otherwise.
84 @param call The thread call to execute.
85 */
86extern boolean_t	thread_call_enter(
87						thread_call_t		call);
88/*!
89 @function thread_call_enter1
90 @abstract Submit a thread call work item for immediate execution, with an extra parameter.
91 @discussion This routine is identical to thread_call_enter(), except that
92 the second parameter to the callback is specified.
93 @result TRUE if the call was already pending for either delayed or immediate
94 execution, FALSE otherwise.
95 @param call The thread call to execute.
96 @param param1 Parameter to pass callback.
97 */
98extern boolean_t	thread_call_enter1(
99						thread_call_t		call,
100						thread_call_param_t	param1);
101
102/*!
103 @function thread_call_enter_delayed
104 @abstract Submit a thread call to be executed at some point in the future.
105 @discussion If the work item is already scheduled for delayed or immediate execution,
106 and it has not yet begun to run, that invocation will be cancelled in favor of execution
107 at the newly specified time.  Note that if a thread call is rescheduled from its own callback,
108 then multiple invocations of the callback may be in flight at the same time.
109 @result TRUE if the call was already pending for either delayed or immediate
110 execution, FALSE otherwise.
111 @param call The thread call to execute.
112 @param deadline Time, in absolute time units, at which to execute callback.
113 */
114extern boolean_t	thread_call_enter_delayed(
115						thread_call_t		call,
116						uint64_t		deadline);
117/*!
118 @function thread_call_enter1_delayed
119 @abstract Submit a thread call to be executed at some point in the future, with an extra parameter.
120 @discussion This routine is identical to thread_call_enter_delayed(),
121 except that a second parameter to the callback is specified.
122 @result TRUE if the call was already pending for either delayed or immediate
123 execution, FALSE otherwise.
124 @param call The thread call to execute.
125 @param param1 Second parameter to callback.
126 @param deadline Time, in absolute time units, at which to execute callback.
127 */
128extern boolean_t	thread_call_enter1_delayed(
129						thread_call_t		call,
130						thread_call_param_t	param1,
131						uint64_t		deadline);
132#ifdef XNU_KERNEL_PRIVATE
133
134/*
135 * Flags to alter the default timer/timeout coalescing behavior
136 * on a per-thread_call basis.
137 *
138 * The SYS urgency classes indicate that the thread_call is not
139 * directly related to the current thread at the time the thread_call
140 * is entered, so it is ignored in the calculation entirely (only
141 * the subclass specified is used).
142 *
143 * The USER flags indicate that both the current thread scheduling and QoS
144 * attributes, in addition to the per-thread_call urgency specification,
145 * are used to establish coalescing behavior.
146 */
147#define THREAD_CALL_DELAY_SYS_NORMAL		TIMEOUT_URGENCY_SYS_NORMAL
148#define THREAD_CALL_DELAY_SYS_CRITICAL		TIMEOUT_URGENCY_SYS_CRITICAL
149#define THREAD_CALL_DELAY_SYS_BACKGROUND	TIMEOUT_URGENCY_SYS_BACKGROUND
150
151#define THREAD_CALL_DELAY_USER_MASK		TIMEOUT_URGENCY_USER_MASK
152#define THREAD_CALL_DELAY_USER_NORMAL		TIMEOUT_URGENCY_USER_NORMAL
153#define THREAD_CALL_DELAY_USER_CRITICAL		TIMEOUT_URGENCY_USER_CRITICAL
154#define THREAD_CALL_DELAY_USER_BACKGROUND	TIMEOUT_URGENCY_USER_BACKGROUND
155
156#define THREAD_CALL_DELAY_URGENCY_MASK		TIMEOUT_URGENCY_MASK
157
158/*
159 * Indicate that a specific leeway value is being provided (otherwise
160 * the leeway parameter is ignored).  The supplied value can currently
161 * only be used to extend the leeway calculated internally from the
162 * urgency class provided.
163 */
164#define THREAD_CALL_DELAY_LEEWAY		TIMEOUT_URGENCY_LEEWAY
165
166/*!
167 @function thread_call_enter_delayed_with_leeway
168 @abstract Submit a thread call to be executed at some point in the future.
169 @discussion If the work item is already scheduled for delayed or immediate execution,
170 and it has not yet begun to run, that invocation will be cancelled in favor of execution
171 at the newly specified time.  Note that if a thread call is rescheduled from its own callback,
172 then multiple invocations of the callback may be in flight at the same time.
173 @result TRUE if the call was already pending for either delayed or immediate
174 execution, FALSE otherwise.
175 @param call The thread call to execute.
176 @param param1 Second parameter to callback.
177 @param deadline Time, in absolute time units, at which to execute callback.
178 @param leeway Time delta, in absolute time units, which sets range of time allowing kernel
179        to decide appropriate time to run.
180 @param flags configuration for timers in kernel.
181 */
182extern boolean_t	thread_call_enter_delayed_with_leeway(
183						thread_call_t		call,
184						thread_call_param_t	param1,
185						uint64_t		deadline,
186						uint64_t		leeway,
187						uint32_t		flags);
188
189#endif /* XNU_KERNEL_PRIVATE */
190
191/*!
192 @function thread_call_cancel
193 @abstract Attempt to cancel a pending invocation of a thread call.
194 @discussion Attempt to cancel a thread call which has been scheduled
195 for execution with a thread_call_enter* variant.  If the call has not
196 yet begun executing, the pending invocation will be cancelled and TRUE
197 will be returned.  If the work item has already begun executing,
198 thread_call_cancel will return FALSE immediately; the callback may be
199 about to run, currently running, or already done executing.
200 @result TRUE if the call was successfully cancelled, FALSE otherwise.
201 */
202extern boolean_t	thread_call_cancel(
203						thread_call_t		call);
204/*!
205 @function thread_call_cancel_wait
206 @abstract Attempt to cancel a pending invocation of a thread call.
207 If unable to cancel, wait for current invocation to finish.
208 @discussion Attempt to cancel a thread call which has been scheduled
209 for execution with a thread_call_enter* variant.  If the call has not
210 yet begun executing, the pending invocation will be cancelled and TRUE
211 will be returned.  If the work item has already begun executing,
212 thread_call_cancel_wait waits for the most recent invocation to finish. When
213 called on a work item which has already finished, it will return FALSE immediately.
214 Note that this routine can only be used on thread calls set up with either
215 thread_call_allocate or thread_call_allocate_with_priority, and that invocations
216 of the thread call <i>after</i> the current invocation may be in flight when
217 thread_call_cancel_wait returns.
218 @result TRUE if the call was successfully cancelled, FALSE otherwise.
219 */
220extern boolean_t	thread_call_cancel_wait(
221						thread_call_t		call);
222
223 /*!
224  @function thread_call_allocate
225  @abstract Allocate a thread call to execute with default (high) priority.
226  @discussion  Allocates a thread call that will run with properties of
227  THREAD_CALL_PRIORITY_HIGH, binding the first parameter to the callback.
228  @param func Callback to invoke when thread call is scheduled.
229  @param param0 First argument ot pass to callback.
230  @result Thread call which can be passed to thread_call_enter variants.
231  */
232extern thread_call_t	thread_call_allocate(
233						thread_call_func_t	func,
234						thread_call_param_t	param0);
235
236 /*!
237  @function thread_call_allocate_with_priority
238  @abstract Allocate a thread call to execute with a specified priority.
239  @discussion Identical to thread_call_allocate, except that priority
240  is specified by caller.
241  @param func Callback to invoke when thread call is scheduled.
242  @param param0 First argument to pass to callback.
243  @param pri Priority of item.
244  @result Thread call which can be passed to thread_call_enter variants.
245  */
246extern thread_call_t	thread_call_allocate_with_priority(
247						thread_call_func_t	func,
248						thread_call_param_t	param0,
249						thread_call_priority_t  pri);
250
251/*!
252 @function thread_call_free
253 @abstract Release a thread call.
254 @discussion Should only be used on thread calls allocated with thread_call_allocate
255 or thread_call_allocate_with_priority.  Once thread_call_free has been called,
256 no other operations may be performed on a thread call.  If the thread call is
257 currently pending, thread_call_free will return FALSE and will have no effect.
258 Calling thread_call_free from a thread call's own callback is safe; the work
259 item is not considering "pending" at that point.
260 @result TRUE if the thread call has been successfully released, else FALSE.
261 @param call The thread call to release.
262 */
263extern boolean_t	thread_call_free(
264						thread_call_t		call);
265
266/*!
267 @function thread_call_isactive
268 @abstract Determine whether a thread call is pending or currently executing.
269 @param call Thread call to examine.
270 @result TRUE if the thread call is either scheduled for execution (immediately
271 or at some point in the future) or is currently executing.
272 */
273boolean_t		thread_call_isactive(
274						thread_call_t call);
275__END_DECLS
276
277#ifdef	MACH_KERNEL_PRIVATE
278
279#include <kern/call_entry.h>
280
281struct thread_call {
282	struct call_entry 		tc_call;	/* Must be first */
283	uint64_t			tc_submit_count;
284	uint64_t			tc_finish_count;
285	uint64_t			ttd; /* Time to deadline at creation */
286	uint64_t			tc_soft_deadline;
287	thread_call_priority_t		tc_pri;
288	uint32_t			tc_flags;
289	int32_t				tc_refs;
290};
291
292#define THREAD_CALL_ALLOC		0x01
293#define THREAD_CALL_WAIT		0x02
294#define THREAD_CALL_DELAYED		0x04
295#define THREAD_CALL_RATELIMITED		TIMEOUT_URGENCY_RATELIMITED
296
297typedef struct thread_call thread_call_data_t;
298
299extern void		thread_call_initialize(void);
300
301extern void		thread_call_setup(
302					thread_call_t			call,
303					thread_call_func_t		func,
304					thread_call_param_t		param0);
305
306extern void 		thread_call_delayed_timer_rescan_all(void);
307#endif	/* MACH_KERNEL_PRIVATE */
308
309#ifdef	XNU_KERNEL_PRIVATE
310
311__BEGIN_DECLS
312
313/*
314 * These routines are equivalent to their thread_call_enter_XXX
315 * variants, only the thread_call_t is allocated out of a
316 * fixed preallocated pool of memory, and will panic if the pool
317 * is exhausted.
318 */
319
320extern void		thread_call_func_delayed(
321					thread_call_func_t		func,
322					thread_call_param_t		param,
323					uint64_t			deadline);
324
325extern void		thread_call_func_delayed_with_leeway(
326						thread_call_func_t		func,
327						thread_call_param_t		param,
328						uint64_t		deadline,
329						uint64_t		leeway,
330						uint32_t		flags);
331
332extern boolean_t	thread_call_func_cancel(
333						thread_call_func_t	func,
334						thread_call_param_t	param,
335						boolean_t		cancel_all);
336__END_DECLS
337
338#endif	/* XNU_KERNEL_PRIVATE */
339
340#endif	/* _KERN_THREAD_CALL_H_ */
341