]> git.saurik.com Git - apple/xnu.git/blame - osfmk/kern/thread_call.h
xnu-2050.9.2.tar.gz
[apple/xnu.git] / osfmk / kern / thread_call.h
CommitLineData
1c79356b 1/*
c910b4d9 2 * Copyright (c) 1993-1995, 1999-2008 Apple Inc. All rights reserved.
1c79356b 3 *
2d21ac55 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b 5 *
2d21ac55
A
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.
8f6c56a5 14 *
2d21ac55
A
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
8f6c56a5
A
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55
A
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.
8f6c56a5 25 *
2d21ac55 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b 27 */
316670eb
A
28
29/*!
30 @header thread_call.h
31 @discussion Facilities for executing work asynchronously.
1c79356b
A
32 */
33
34#ifndef _KERN_THREAD_CALL_H_
35#define _KERN_THREAD_CALL_H_
36
1c79356b
A
37#include <mach/mach_types.h>
38
0b4e3aa0
A
39#include <kern/clock.h>
40
91447636
A
41#include <sys/cdefs.h>
42
316670eb
A
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
91447636 73__BEGIN_DECLS
1c79356b 74
316670eb
A
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 */
c910b4d9
A
86extern boolean_t thread_call_enter(
87 thread_call_t call);
316670eb
A
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 */
c910b4d9 98extern boolean_t thread_call_enter1(
316670eb
A
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 */
c910b4d9
A
114extern boolean_t thread_call_enter_delayed(
115 thread_call_t call,
316670eb
A
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 */
c910b4d9 128extern boolean_t thread_call_enter1_delayed(
316670eb
A
129 thread_call_t call,
130 thread_call_param_t param1,
131 uint64_t deadline);
132
133/*!
134 @function thread_call_cancel
135 @abstract Attempt to cancel a pending invocation of a thread call.
136 @discussion Attempt to cancel a thread call which has been scheduled
137 for execution with a thread_call_enter* variant. If the call has not
138 yet begun executing, the pending invocation will be cancelled and TRUE
139 will be returned. If the work item has already begun executing,
140 thread_call_cancel will return FALSE immediately; the callback may be
141 about to run, currently running, or already done executing.
142 @result TRUE if the call was successfully cancelled, FALSE otherwise.
143 */
c910b4d9
A
144extern boolean_t thread_call_cancel(
145 thread_call_t call);
316670eb
A
146/*!
147 @function thread_call_cancel_wait
148 @abstract Attempt to cancel a pending invocation of a thread call.
149 If unable to cancel, wait for current invocation to finish.
150 @discussion Attempt to cancel a thread call which has been scheduled
151 for execution with a thread_call_enter* variant. If the call has not
152 yet begun executing, the pending invocation will be cancelled and TRUE
153 will be returned. If the work item has already begun executing,
154 thread_call_cancel_wait waits for the most recent invocation to finish. When
155 called on a work item which has already finished, it will return FALSE immediately.
156 Note that this routine can only be used on thread calls set up with either
157 thread_call_allocate or thread_call_allocate_with_priority, and that invocations
158 of the thread call <i>after</i> the current invocation may be in flight when
159 thread_call_cancel_wait returns.
160 @result TRUE if the call was successfully cancelled, FALSE otherwise.
161 */
162extern boolean_t thread_call_cancel_wait(
163 thread_call_t call);
c910b4d9 164
316670eb
A
165 /*!
166 @function thread_call_allocate
167 @abstract Allocate a thread call to execute with default (high) priority.
168 @discussion Allocates a thread call that will run with properties of
169 THREAD_CALL_PRIORITY_HIGH, binding the first parameter to the callback.
170 @param func Callback to invoke when thread call is scheduled.
171 @param param0 First argument ot pass to callback.
172 @result Thread call which can be passed to thread_call_enter variants.
173 */
c910b4d9 174extern thread_call_t thread_call_allocate(
316670eb
A
175 thread_call_func_t func,
176 thread_call_param_t param0);
177
178 /*!
179 @function thread_call_allocate_with_priority
180 @abstract Allocate a thread call to execute with a specified priority.
181 @discussion Identical to thread_call_allocate, except that priority
182 is specified by caller.
183 @param func Callback to invoke when thread call is scheduled.
184 @param param0 First argument to pass to callback.
185 @param pri Priority of item.
186 @result Thread call which can be passed to thread_call_enter variants.
187 */
188extern thread_call_t thread_call_allocate_with_priority(
189 thread_call_func_t func,
190 thread_call_param_t param0,
191 thread_call_priority_t pri);
192
193/*!
194 @function thread_call_free
195 @abstract Release a thread call.
196 @discussion Should only be used on thread calls allocated with thread_call_allocate
197 or thread_call_allocate_with_priority. Once thread_call_free has been called,
198 no other operations may be performed on a thread call. If the thread call is
199 currently pending, thread_call_free will return FALSE and will have no effect.
200 Calling thread_call_free from a thread call's own callback is safe; the work
201 item is not considering "pending" at that point.
202 @result TRUE if the thread call has been successfully released, else FALSE.
203 @param call The thread call to release.
204 */
205extern boolean_t thread_call_free(
206 thread_call_t call);
1c79356b 207
316670eb
A
208/*!
209 @function thread_call_isactive
210 @abstract Determine whether a thread call is pending or currently executing.
211 @param call Thread call to examine.
212 @result TRUE if the thread call is either scheduled for execution (immediately
213 or at some point in the future) or is currently executing.
214 */
215boolean_t thread_call_isactive(
216 thread_call_t call);
91447636
A
217__END_DECLS
218
219#ifdef MACH_KERNEL_PRIVATE
220
221#include <kern/call_entry.h>
222
316670eb
A
223struct thread_call {
224 struct call_entry tc_call; /* Must be first */
225 uint64_t tc_submit_count;
226 uint64_t tc_finish_count;
227 thread_call_priority_t tc_pri;
228
229 uint32_t tc_flags;
230 int32_t tc_refs;
231};
232
233#define THREAD_CALL_ALLOC 0x01
234#define THREAD_CALL_WAIT 0x02
235
236typedef struct thread_call thread_call_data_t;
91447636 237
c910b4d9 238extern void thread_call_initialize(void);
91447636 239
c910b4d9
A
240extern void thread_call_setup(
241 thread_call_t call,
242 thread_call_func_t func,
243 thread_call_param_t param0);
91447636 244
91447636
A
245#endif /* MACH_KERNEL_PRIVATE */
246
247#ifdef KERNEL_PRIVATE
9bccf70c 248
91447636 249__BEGIN_DECLS
9bccf70c 250
1c79356b 251/*
91447636 252 * Obsolete interfaces.
1c79356b 253 */
9bccf70c 254
b0d623f7
A
255#ifndef __LP64__
256
c910b4d9
A
257extern boolean_t thread_call_is_delayed(
258 thread_call_t call,
316670eb 259 uint64_t *deadline);
c910b4d9
A
260
261extern void thread_call_func(
262 thread_call_func_t func,
263 thread_call_param_t param,
316670eb 264 boolean_t unique_call);
c910b4d9
A
265
266extern void thread_call_func_delayed(
267 thread_call_func_t func,
268 thread_call_param_t param,
316670eb 269 uint64_t deadline);
c910b4d9
A
270
271extern boolean_t thread_call_func_cancel(
316670eb
A
272 thread_call_func_t func,
273 thread_call_param_t param,
274 boolean_t cancel_all);
9bccf70c 275
b0d623f7
A
276#else /* __LP64__ */
277
278#ifdef XNU_KERNEL_PRIVATE
279
280extern void thread_call_func_delayed(
281 thread_call_func_t func,
282 thread_call_param_t param,
316670eb 283 uint64_t deadline);
b0d623f7
A
284
285extern boolean_t thread_call_func_cancel(
316670eb
A
286 thread_call_func_t func,
287 thread_call_param_t param,
288 boolean_t cancel_all);
b0d623f7
A
289
290#endif /* XNU_KERNEL_PRIVATE */
291
292#endif /* __LP64__ */
293
91447636 294#ifndef MACH_KERNEL_PRIVATE
9bccf70c 295
b0d623f7
A
296#ifndef __LP64__
297
91447636 298#ifndef ABSOLUTETIME_SCALAR_TYPE
0b4e3aa0
A
299
300#define thread_call_enter_delayed(a, b) \
301 thread_call_enter_delayed((a), __OSAbsoluteTime(b))
302
303#define thread_call_enter1_delayed(a, b, c) \
304 thread_call_enter1_delayed((a), (b), __OSAbsoluteTime(c))
305
306#define thread_call_is_delayed(a, b) \
307 thread_call_is_delayed((a), __OSAbsoluteTimePtr(b))
308
309#define thread_call_func_delayed(a, b, c) \
310 thread_call_func_delayed((a), (b), __OSAbsoluteTime(c))
311
91447636
A
312#endif /* ABSOLUTETIME_SCALAR_TYPE */
313
b0d623f7
A
314#endif /* __LP64__ */
315
91447636
A
316#endif /* MACH_KERNEL_PRIVATE */
317
318__END_DECLS
319
320#endif /* KERNEL_PRIVATE */
0b4e3aa0 321
91447636 322#endif /* _KERN_THREAD_CALL_H_ */