]>
Commit | Line | Data |
---|---|---|
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 |
43 | struct thread_call; |
44 | typedef struct thread_call *thread_call_t; | |
45 | ||
46 | typedef void *thread_call_param_t; | |
47 | typedef 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 | */ | |
66 | typedef 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 |
86 | extern 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 | 98 | extern 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 |
114 | extern 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 | 128 | extern 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 |
144 | extern 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 | */ | |
162 | extern 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 | 174 | extern 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 | */ | |
188 | extern 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 | */ | |
205 | extern 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 | */ | |
215 | boolean_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 |
223 | struct 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 | ||
236 | typedef struct thread_call thread_call_data_t; | |
91447636 | 237 | |
c910b4d9 | 238 | extern void thread_call_initialize(void); |
91447636 | 239 | |
c910b4d9 A |
240 | extern 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 |
257 | extern boolean_t thread_call_is_delayed( |
258 | thread_call_t call, | |
316670eb | 259 | uint64_t *deadline); |
c910b4d9 A |
260 | |
261 | extern 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 | |
266 | extern 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 | |
271 | extern 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 | ||
280 | extern 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 | |
285 | extern 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_ */ |