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 #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  * Indicates that the time parameters should be interpreted as
 168  * mach_continuous_time values, rather than mach_absolute_time and the timer
 169  * be programmed to fire based on continuous time.
 170  */
 171 #define THREAD_CALL_CONTINUOUS  0x100
 172
 173 /*!
 174  @function thread_call_enter_delayed_with_leeway
 175  @abstract Submit a thread call to be executed at some point in the future.
 176  @discussion If the work item is already scheduled for delayed or immediate execution,
 177  and it has not yet begun to run, that invocation will be cancelled in favor of execution
 178  at the newly specified time.  Note that if a thread call is rescheduled from its own callback,
 179  then multiple invocations of the callback may be in flight at the same time.
 180  @result TRUE if the call was already pending for either delayed or immediate
 181  execution, FALSE otherwise.
 182  @param call The thread call to execute.
 183  @param param1 Second parameter to callback.
 184  @param deadline Time, in absolute time units, at which to execute callback.
 185  @param leeway Time delta, in absolute time units, which sets range of time allowing kernel
 186         to decide appropriate time to run.
 187  @param flags configuration for timers in kernel.
 188  */
 189 extern boolean_t        thread_call_enter_delayed_with_leeway(
 190                                                 thread_call_t           call,
 191                                                 thread_call_param_t     param1,
 192                                                 uint64_t                deadline,
 193                                                 uint64_t                leeway,
 194                                                 uint32_t                flags);
 195
 196 #endif /* XNU_KERNEL_PRIVATE */
 197
 198 /*!
 199  @function thread_call_cancel
 200  @abstract Attempt to cancel a pending invocation of a thread call.
 201  @discussion Attempt to cancel a thread call which has been scheduled
 202  for execution with a thread_call_enter* variant.  If the call has not
 203  yet begun executing, the pending invocation will be cancelled and TRUE
 204  will be returned.  If the work item has already begun executing,
 205  thread_call_cancel will return FALSE immediately; the callback may be
 206  about to run, currently running, or already done executing.
 207  @result TRUE if the call was successfully cancelled, FALSE otherwise.
 208  */
 209 extern boolean_t        thread_call_cancel(
 210                                                 thread_call_t           call);
 211 /*!
 212  @function thread_call_cancel_wait
 213  @abstract Attempt to cancel a pending invocation of a thread call.
 214  If unable to cancel, wait for current invocation to finish.
 215  @discussion Attempt to cancel a thread call which has been scheduled
 216  for execution with a thread_call_enter* variant.  If the call has not
 217  yet begun executing, the pending invocation will be cancelled and TRUE
 218  will be returned.  If the work item has already begun executing,
 219  thread_call_cancel_wait waits for the most recent invocation to finish. When
 220  called on a work item which has already finished, it will return FALSE immediately.
 221  Note that this routine can only be used on thread calls set up with either
 222  thread_call_allocate or thread_call_allocate_with_priority, and that invocations
 223  of the thread call <i>after</i> the current invocation may be in flight when
 224  thread_call_cancel_wait returns.
 225  @result TRUE if the call was successfully cancelled, FALSE otherwise.
 226  */
 227 extern boolean_t        thread_call_cancel_wait(
 228                                                 thread_call_t           call);
 229
 230  /*!
 231   @function thread_call_allocate
 232   @abstract Allocate a thread call to execute with default (high) priority.
 233   @discussion  Allocates a thread call that will run with properties of
 234   THREAD_CALL_PRIORITY_HIGH, binding the first parameter to the callback.
 235   @param func Callback to invoke when thread call is scheduled.
 236   @param param0 First argument ot pass to callback.
 237   @result Thread call which can be passed to thread_call_enter variants.
 238   */
 239 extern thread_call_t    thread_call_allocate(
 240                                                 thread_call_func_t      func,
 241                                                 thread_call_param_t     param0);
 242
 243  /*!
 244   @function thread_call_allocate_with_priority
 245   @abstract Allocate a thread call to execute with a specified priority.
 246   @discussion Identical to thread_call_allocate, except that priority
 247   is specified by caller.
 248   @param func Callback to invoke when thread call is scheduled.
 249   @param param0 First argument to pass to callback.
 250   @param pri Priority of item.
 251   @result Thread call which can be passed to thread_call_enter variants.
 252   */
 253 extern thread_call_t    thread_call_allocate_with_priority(
 254                                                 thread_call_func_t      func,
 255                                                 thread_call_param_t     param0,
 256                                                 thread_call_priority_t  pri);
 257
 258 /*!
 259  @function thread_call_free
 260  @abstract Release a thread call.
 261  @discussion Should only be used on thread calls allocated with thread_call_allocate
 262  or thread_call_allocate_with_priority.  Once thread_call_free has been called,
 263  no other operations may be performed on a thread call.  If the thread call is
 264  currently pending, thread_call_free will return FALSE and will have no effect.
 265  Calling thread_call_free from a thread call's own callback is safe; the work
 266  item is not considering "pending" at that point.
 267  @result TRUE if the thread call has been successfully released, else FALSE.
 268  @param call The thread call to release.
 269  */
 270 extern boolean_t        thread_call_free(
 271                                                 thread_call_t           call);
 272
 273 /*!
 274  @function thread_call_isactive
 275  @abstract Determine whether a thread call is pending or currently executing.
 276  @param call Thread call to examine.
 277  @result TRUE if the thread call is either scheduled for execution (immediately
 278  or at some point in the future) or is currently executing.
 279  */
 280 boolean_t               thread_call_isactive(
 281                                                 thread_call_t call);
 282 __END_DECLS
 283
 284 #ifdef  MACH_KERNEL_PRIVATE
 285
 286 #include <kern/call_entry.h>
 287
 288 struct thread_call {
 289         struct call_entry       tc_call;        /* Must be first */
 290         uint64_t                        tc_submit_count;
 291         uint64_t                        tc_finish_count;
 292         uint64_t                        ttd; /* Time to deadline at creation */
 293         uint64_t                        tc_soft_deadline;
 294         thread_call_priority_t          tc_pri;
 295         uint32_t                        tc_flags;
 296         int32_t                         tc_refs;
 297 };
 298
 299 #define THREAD_CALL_ALLOC       0x01
 300 #define THREAD_CALL_WAIT        0x02
 301 #define THREAD_CALL_DELAYED     0x04
 302 #define THREAD_CALL_RATELIMITED TIMEOUT_URGENCY_RATELIMITED
 303
 304 typedef struct thread_call thread_call_data_t;
 305
 306 extern void             thread_call_initialize(void);
 307
 308 extern void             thread_call_setup(
 309                                         thread_call_t                   call,
 310                                         thread_call_func_t              func,
 311                                         thread_call_param_t             param0);
 312
 313 extern void             thread_call_delayed_timer_rescan_all(void);
 314 #endif  /* MACH_KERNEL_PRIVATE */
 315
 316 #ifdef  XNU_KERNEL_PRIVATE
 317
 318 __BEGIN_DECLS
 319
 320 /*
 321  * These routines are equivalent to their thread_call_enter_XXX
 322  * variants, only the thread_call_t is allocated out of a
 323  * fixed preallocated pool of memory, and will panic if the pool
 324  * is exhausted.
 325  */
 326
 327 extern void             thread_call_func_delayed(
 328                                         thread_call_func_t              func,
 329                                         thread_call_param_t             param,
 330                                         uint64_t                        deadline);
 331
 332 extern void             thread_call_func_delayed_with_leeway(
 333                                                 thread_call_func_t              func,
 334                                                 thread_call_param_t             param,
 335                                                 uint64_t                deadline,
 336                                                 uint64_t                leeway,
 337                                                 uint32_t                flags);
 338
 339 extern boolean_t        thread_call_func_cancel(
 340                                                 thread_call_func_t      func,
 341                                                 thread_call_param_t     param,
 342                                                 boolean_t               cancel_all);
 343
 344 /*
 345  * Called on the wake path to adjust the thread callouts running in mach_continuous_time
 346  */
 347 void                            adjust_cont_time_thread_calls(void);
 348
 349 __END_DECLS
 350
 351 #endif  /* XNU_KERNEL_PRIVATE */
 352
 353 #endif  /* _KERN_THREAD_CALL_H_ */