osfmk/kern/thread_call.h

   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
  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
  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  */
  86 extern 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  */
  98 extern 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  */
 114 extern 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  */
 128 extern boolean_t        thread_call_enter1_delayed(
 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  */
 144 extern boolean_t        thread_call_cancel(
 145                                                 thread_call_t           call);
 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);
 164
 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   */
 174 extern thread_call_t    thread_call_allocate(
 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);
 207
 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);
 217 __END_DECLS
 218
 219 #ifdef  MACH_KERNEL_PRIVATE
 220
 221 #include <kern/call_entry.h>
 222
 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         uint64_t                        ttd; /* Time to deadline at creation */
 233 };
 234
 235 #define THREAD_CALL_ALLOC               0x01
 236 #define THREAD_CALL_WAIT                0x02
 237
 238 typedef struct thread_call thread_call_data_t;
 239
 240 extern void             thread_call_initialize(void);
 241
 242 extern void             thread_call_setup(
 243                                         thread_call_t                   call,
 244                                         thread_call_func_t              func,
 245                                         thread_call_param_t             param0);
 246
 247 #endif  /* MACH_KERNEL_PRIVATE */
 248
 249 #ifdef  KERNEL_PRIVATE
 250
 251 __BEGIN_DECLS
 252
 253 /*
 254  * Obsolete interfaces.
 255  */
 256
 257 #ifndef __LP64__
 258
 259 extern boolean_t        thread_call_is_delayed(
 260                                                 thread_call_t           call,
 261                                                 uint64_t                *deadline);
 262
 263 extern void             thread_call_func(
 264                                         thread_call_func_t              func,
 265                                         thread_call_param_t             param,
 266                                         boolean_t                       unique_call);
 267
 268 extern void             thread_call_func_delayed(
 269                                         thread_call_func_t              func,
 270                                         thread_call_param_t             param,
 271                                         uint64_t                        deadline);
 272
 273 extern boolean_t        thread_call_func_cancel(
 274                                                 thread_call_func_t      func,
 275                                                 thread_call_param_t     param,
 276                                                 boolean_t               cancel_all);
 277
 278 #else   /* __LP64__ */
 279
 280 #ifdef  XNU_KERNEL_PRIVATE
 281
 282 extern void             thread_call_func_delayed(
 283                                         thread_call_func_t              func,
 284                                         thread_call_param_t             param,
 285                                         uint64_t                        deadline);
 286
 287 extern boolean_t        thread_call_func_cancel(
 288                                                 thread_call_func_t      func,
 289                                                 thread_call_param_t     param,
 290                                                 boolean_t               cancel_all);
 291
 292 #endif  /* XNU_KERNEL_PRIVATE */
 293
 294 #endif  /* __LP64__ */
 295
 296 #ifndef MACH_KERNEL_PRIVATE
 297
 298 #ifndef __LP64__
 299
 300 #ifndef ABSOLUTETIME_SCALAR_TYPE
 301
 302 #define thread_call_enter_delayed(a, b) \
 303         thread_call_enter_delayed((a), __OSAbsoluteTime(b))
 304
 305 #define thread_call_enter1_delayed(a, b, c)     \
 306         thread_call_enter1_delayed((a), (b), __OSAbsoluteTime(c))
 307
 308 #define thread_call_is_delayed(a, b)    \
 309         thread_call_is_delayed((a), __OSAbsoluteTimePtr(b))
 310
 311 #define thread_call_func_delayed(a, b, c)       \
 312         thread_call_func_delayed((a), (b), __OSAbsoluteTime(c))
 313
 314 #endif  /* ABSOLUTETIME_SCALAR_TYPE */
 315
 316 #endif  /* __LP64__ */
 317
 318 #endif  /* MACH_KERNEL_PRIVATE */
 319
 320 __END_DECLS
 321
 322 #endif  /* KERNEL_PRIVATE */
 323
 324 #endif  /* _KERN_THREAD_CALL_H_ */