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  @constant THREAD_CALL_PRIORITY_KERNEL_HIGH Importance higher than most kernel
  66  threads.
  67  */
  68 typedef enum {
  69         THREAD_CALL_PRIORITY_HIGH        = 0,
  70         THREAD_CALL_PRIORITY_KERNEL      = 1,
  71         THREAD_CALL_PRIORITY_USER        = 2,
  72         THREAD_CALL_PRIORITY_LOW         = 3,
  73         THREAD_CALL_PRIORITY_KERNEL_HIGH = 4
  74 } thread_call_priority_t;
  75
  76 enum {
  77         /* if call is re-submitted while the call is executing on a call thread, then delay the re-enqueue until it returns */
  78         THREAD_CALL_OPTIONS_ONCE   = 0x00000001,
  79 #ifdef XNU_KERNEL_PRIVATE
  80         /* execute call from the timer interrupt instead of from the thread call thread, private interface for IOTES workloop signaling */
  81         THREAD_CALL_OPTIONS_SIGNAL = 0x00000002,
  82 #endif /* XNU_KERNEL_PRIVATE */
  83 };
  84 typedef uint32_t thread_call_options_t;
  85
  86 __BEGIN_DECLS
  87
  88 /*!
  89  @function thread_call_enter
  90  @abstract Submit a thread call work item for immediate execution.
  91  @discussion If the work item is already scheduled for delayed execution, and it has
  92  not yet begun to run, that delayed invocation will be cancelled.  Note that if a
  93  thread call is rescheduled from its own callback, then multiple invocations of the
  94  callback may be in flight at the same time.
  95  @result TRUE if the call was already pending for either delayed or immediate
  96  execution, FALSE otherwise.
  97  @param call The thread call to execute.
  98  */
  99 extern boolean_t        thread_call_enter(
 100                                                 thread_call_t           call);
 101 /*!
 102  @function thread_call_enter1
 103  @abstract Submit a thread call work item for immediate execution, with an extra parameter.
 104  @discussion This routine is identical to thread_call_enter(), except that
 105  the second parameter to the callback is specified.
 106  @result TRUE if the call was already pending for either delayed or immediate
 107  execution, FALSE otherwise.
 108  @param call The thread call to execute.
 109  @param param1 Parameter to pass callback.
 110  */
 111 extern boolean_t        thread_call_enter1(
 112                                                 thread_call_t           call,
 113                                                 thread_call_param_t     param1);
 114
 115 /*!
 116  @function thread_call_enter_delayed
 117  @abstract Submit a thread call to be executed at some point in the future.
 118  @discussion If the work item is already scheduled for delayed or immediate execution,
 119  and it has not yet begun to run, that invocation will be cancelled in favor of execution
 120  at the newly specified time.  Note that if a thread call is rescheduled from its own callback,
 121  then multiple invocations of the callback may be in flight at the same time.
 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 deadline Time, in absolute time units, at which to execute callback.
 126  */
 127 extern boolean_t        thread_call_enter_delayed(
 128                                                 thread_call_t           call,
 129                                                 uint64_t                deadline);
 130 /*!
 131  @function thread_call_enter1_delayed
 132  @abstract Submit a thread call to be executed at some point in the future, with an extra parameter.
 133  @discussion This routine is identical to thread_call_enter_delayed(),
 134  except that a second parameter to the callback is specified.
 135  @result TRUE if the call was already pending for either delayed or immediate
 136  execution, FALSE otherwise.
 137  @param call The thread call to execute.
 138  @param param1 Second parameter to callback.
 139  @param deadline Time, in absolute time units, at which to execute callback.
 140  */
 141 extern boolean_t        thread_call_enter1_delayed(
 142                                                 thread_call_t           call,
 143                                                 thread_call_param_t     param1,
 144                                                 uint64_t                deadline);
 145 #ifdef XNU_KERNEL_PRIVATE
 146
 147 /*
 148  * Flags to alter the default timer/timeout coalescing behavior
 149  * on a per-thread_call basis.
 150  *
 151  * The SYS urgency classes indicate that the thread_call is not
 152  * directly related to the current thread at the time the thread_call
 153  * is entered, so it is ignored in the calculation entirely (only
 154  * the subclass specified is used).
 155  *
 156  * The USER flags indicate that both the current thread scheduling and QoS
 157  * attributes, in addition to the per-thread_call urgency specification,
 158  * are used to establish coalescing behavior.
 159  */
 160 #define THREAD_CALL_DELAY_SYS_NORMAL            TIMEOUT_URGENCY_SYS_NORMAL
 161 #define THREAD_CALL_DELAY_SYS_CRITICAL          TIMEOUT_URGENCY_SYS_CRITICAL
 162 #define THREAD_CALL_DELAY_SYS_BACKGROUND        TIMEOUT_URGENCY_SYS_BACKGROUND
 163
 164 #define THREAD_CALL_DELAY_USER_MASK             TIMEOUT_URGENCY_USER_MASK
 165 #define THREAD_CALL_DELAY_USER_NORMAL           TIMEOUT_URGENCY_USER_NORMAL
 166 #define THREAD_CALL_DELAY_USER_CRITICAL         TIMEOUT_URGENCY_USER_CRITICAL
 167 #define THREAD_CALL_DELAY_USER_BACKGROUND       TIMEOUT_URGENCY_USER_BACKGROUND
 168
 169 #define THREAD_CALL_DELAY_URGENCY_MASK          TIMEOUT_URGENCY_MASK
 170
 171 /*
 172  * Indicate that a specific leeway value is being provided (otherwise
 173  * the leeway parameter is ignored).  The supplied value can currently
 174  * only be used to extend the leeway calculated internally from the
 175  * urgency class provided.
 176  */
 177 #define THREAD_CALL_DELAY_LEEWAY                TIMEOUT_URGENCY_LEEWAY
 178
 179 /*
 180  * Indicates that the time parameters should be interpreted as
 181  * mach_continuous_time values, rather than mach_absolute_time and the timer
 182  * be programmed to fire based on continuous time.
 183  */
 184 #define THREAD_CALL_CONTINUOUS  0x100
 185
 186 /*!
 187  @function thread_call_enter_delayed_with_leeway
 188  @abstract Submit a thread call to be executed at some point in the future.
 189  @discussion If the work item is already scheduled for delayed or immediate execution,
 190  and it has not yet begun to run, that invocation will be cancelled in favor of execution
 191  at the newly specified time.  Note that if a thread call is rescheduled from its own callback,
 192  then multiple invocations of the callback may be in flight at the same time.
 193  @result TRUE if the call was already pending for either delayed or immediate
 194  execution, FALSE otherwise.
 195  @param call The thread call to execute.
 196  @param param1 Second parameter to callback.
 197  @param deadline Time, in absolute time units, at which to execute callback.
 198  @param leeway Time delta, in absolute time units, which sets range of time allowing kernel
 199         to decide appropriate time to run.
 200  @param flags configuration for timers in kernel.
 201  */
 202 extern boolean_t        thread_call_enter_delayed_with_leeway(
 203                                                 thread_call_t           call,
 204                                                 thread_call_param_t     param1,
 205                                                 uint64_t                deadline,
 206                                                 uint64_t                leeway,
 207                                                 uint32_t                flags);
 208
 209 #endif /* XNU_KERNEL_PRIVATE */
 210
 211 /*!
 212  @function thread_call_cancel
 213  @abstract Attempt to cancel a pending invocation of a thread call.
 214  @discussion Attempt to cancel a thread call which has been scheduled
 215  for execution with a thread_call_enter* variant.  If the call has not
 216  yet begun executing, the pending invocation will be cancelled and TRUE
 217  will be returned.  If the work item has already begun executing,
 218  thread_call_cancel will return FALSE immediately; the callback may be
 219  about to run, currently running, or already done executing.
 220  @result TRUE if the call was successfully cancelled, FALSE otherwise.
 221  */
 222 extern boolean_t        thread_call_cancel(
 223                                                 thread_call_t           call);
 224 /*!
 225  @function thread_call_cancel_wait
 226  @abstract Attempt to cancel a pending invocation of a thread call.
 227  If unable to cancel, wait for current invocation to finish.
 228  @discussion Attempt to cancel a thread call which has been scheduled
 229  for execution with a thread_call_enter* variant.  If the call has not
 230  yet begun executing, the pending invocation will be cancelled and TRUE
 231  will be returned.  If the work item has already begun executing,
 232  thread_call_cancel_wait waits for the most recent invocation to finish. When
 233  called on a work item which has already finished, it will return FALSE immediately.
 234  Note that this routine can only be used on thread calls set up with either
 235  thread_call_allocate or thread_call_allocate_with_priority, and that invocations
 236  of the thread call <i>after</i> the current invocation may be in flight when
 237  thread_call_cancel_wait returns.
 238  @result TRUE if the call was successfully cancelled, FALSE otherwise.
 239  */
 240 extern boolean_t        thread_call_cancel_wait(
 241                                                 thread_call_t           call);
 242
 243  /*!
 244   @function thread_call_allocate
 245   @abstract Allocate a thread call to execute with default (high) priority.
 246   @discussion  Allocates a thread call that will run with properties of
 247   THREAD_CALL_PRIORITY_HIGH, binding the first parameter to the callback.
 248   @param func Callback to invoke when thread call is scheduled.
 249   @param param0 First argument ot pass to callback.
 250   @result Thread call which can be passed to thread_call_enter variants.
 251   */
 252 extern thread_call_t    thread_call_allocate(
 253                                                 thread_call_func_t      func,
 254                                                 thread_call_param_t     param0);
 255
 256  /*!
 257   @function thread_call_allocate_with_priority
 258   @abstract Allocate a thread call to execute with a specified priority.
 259   @discussion Identical to thread_call_allocate, except that priority
 260   is specified by caller.
 261   @param func Callback to invoke when thread call is scheduled.
 262   @param param0 First argument to pass to callback.
 263   @param pri Priority of item.
 264   @result Thread call which can be passed to thread_call_enter variants.
 265   */
 266 extern thread_call_t    thread_call_allocate_with_priority(
 267                                                 thread_call_func_t      func,
 268                                                 thread_call_param_t     param0,
 269                                                 thread_call_priority_t  pri);
 270
 271  /*!
 272   @function thread_call_allocate_with_options
 273   @abstract Allocate a thread call to execute with a specified priority.
 274   @discussion Identical to thread_call_allocate, except that priority
 275   and options are specified by caller.
 276   @param func Callback to invoke when thread call is scheduled.
 277   @param param0 First argument to pass to callback.
 278   @param pri Priority of item.
 279   @param options Options for item.
 280   @result Thread call which can be passed to thread_call_enter variants.
 281   */
 282 extern thread_call_t    thread_call_allocate_with_options(
 283                                                 thread_call_func_t      func,
 284                                                 thread_call_param_t     param0,
 285                                                 thread_call_priority_t  pri,
 286                                                 thread_call_options_t   options);
 287
 288 #ifdef KERNEL_PRIVATE
 289  /*!
 290   @function thread_call_allocate_with_qos
 291   @abstract Allocate a thread call to execute with a specified QoS.
 292   @discussion Identical to thread_call_allocate_with_options, except it uses the QoS namespace.
 293         Private interface for pthread kext.
 294   @param func Callback to invoke when thread call is scheduled.
 295   @param param0 First argument to pass to callback.
 296   @param qos_tier QoS tier to execute callback at (as in THREAD_QOS_POLICY)
 297   @param options flags from thread_call_options_t to influence the thread call behavior
 298   @result Thread call which can be passed to thread_call_enter variants.
 299   */
 300 extern thread_call_t
 301 thread_call_allocate_with_qos(thread_call_func_t        func,
 302                               thread_call_param_t       param0,
 303                               int                       qos_tier,
 304                               thread_call_options_t     options);
 305
 306 /*!
 307   @function thread_call_wait_once
 308   @abstract Wait for a THREAD_CALL_OPTIONS_ONCE call to finish executing if it is executing
 309   @discussion Only works on THREAD_CALL_OPTIONS_ONCE calls
 310   @param call The thread call to wait for
 311   @result True if it waited, false if it did not wait
 312  */
 313 extern boolean_t
 314 thread_call_wait_once(thread_call_t call);
 315 #endif /* KERNEL_PRIVATE */
 316
 317 /*!
 318  @function thread_call_free
 319  @abstract Release a thread call.
 320  @discussion Should only be used on thread calls allocated with thread_call_allocate
 321  or thread_call_allocate_with_priority.  Once thread_call_free has been called,
 322  no other operations may be performed on a thread call.  If the thread call is
 323  currently pending, thread_call_free will return FALSE and will have no effect.
 324  Calling thread_call_free from a thread call's own callback is safe; the work
 325  item is not considering "pending" at that point.
 326  @result TRUE if the thread call has been successfully released, else FALSE.
 327  @param call The thread call to release.
 328  */
 329 extern boolean_t        thread_call_free(
 330                                                 thread_call_t           call);
 331
 332 /*!
 333  @function thread_call_isactive
 334  @abstract Determine whether a thread call is pending or currently executing.
 335  @param call Thread call to examine.
 336  @result TRUE if the thread call is either scheduled for execution (immediately
 337  or at some point in the future) or is currently executing.
 338  */
 339 boolean_t               thread_call_isactive(
 340                                                 thread_call_t call);
 341 __END_DECLS
 342
 343 #ifdef  MACH_KERNEL_PRIVATE
 344
 345 #include <kern/call_entry.h>
 346
 347 typedef enum {
 348         THREAD_CALL_INDEX_HIGH          = 0,
 349         THREAD_CALL_INDEX_KERNEL        = 1,
 350         THREAD_CALL_INDEX_USER          = 2,
 351         THREAD_CALL_INDEX_LOW           = 3,
 352         THREAD_CALL_INDEX_KERNEL_HIGH   = 4,
 353         THREAD_CALL_INDEX_QOS_UI        = 5,
 354         THREAD_CALL_INDEX_QOS_IN        = 6,
 355         THREAD_CALL_INDEX_QOS_UT        = 7,
 356         THREAD_CALL_INDEX_MAX           = 8,    /* count of thread call indexes */
 357 } thread_call_index_t;
 358
 359 struct thread_call {
 360         struct call_entry               tc_call;                /* Must be first for queue macros */
 361         uint64_t                        tc_submit_count;
 362         uint64_t                        tc_finish_count;
 363         uint64_t                        tc_ttd;                 /* Time to deadline at creation */
 364         uint64_t                        tc_soft_deadline;
 365         thread_call_index_t             tc_index;
 366         uint32_t                        tc_flags;
 367         int32_t                         tc_refs;
 368 };
 369
 370 #define THREAD_CALL_ALLOC       0x01    /* memory owned by thread_call.c */
 371 #define THREAD_CALL_WAIT        0x02    /* thread waiting for call to finish running */
 372 #define THREAD_CALL_DELAYED     0x04    /* deadline based */
 373 #define THREAD_CALL_RUNNING     0x08    /* currently executing on a thread */
 374 #define THREAD_CALL_SIGNAL      0x10    /* call from timer interrupt instead of thread */
 375 #define THREAD_CALL_ONCE        0x20    /* pend the enqueue if re-armed while running */
 376 #define THREAD_CALL_RESCHEDULE  0x40    /* enqueue is pending due to re-arm while running */
 377 #define THREAD_CALL_RATELIMITED TIMEOUT_URGENCY_RATELIMITED     /* 0x80 */
 378 /*      THREAD_CALL_CONTINUOUS  0x100 */
 379
 380 typedef struct thread_call thread_call_data_t;
 381
 382 extern void             thread_call_initialize(void);
 383
 384 extern void             thread_call_setup(
 385                                         thread_call_t                   call,
 386                                         thread_call_func_t              func,
 387                                         thread_call_param_t             param0);
 388
 389 extern void             thread_call_delayed_timer_rescan_all(void);
 390 #endif  /* MACH_KERNEL_PRIVATE */
 391
 392 #ifdef  XNU_KERNEL_PRIVATE
 393
 394 __BEGIN_DECLS
 395
 396 /*
 397  * These routines are equivalent to their thread_call_enter_XXX
 398  * variants, only the thread_call_t is allocated out of a
 399  * fixed preallocated pool of memory, and will panic if the pool
 400  * is exhausted.
 401  */
 402
 403 extern void             thread_call_func_delayed(
 404                                         thread_call_func_t              func,
 405                                         thread_call_param_t             param,
 406                                         uint64_t                        deadline);
 407
 408 extern void             thread_call_func_delayed_with_leeway(
 409                                                 thread_call_func_t              func,
 410                                                 thread_call_param_t             param,
 411                                                 uint64_t                deadline,
 412                                                 uint64_t                leeway,
 413                                                 uint32_t                flags);
 414
 415 /*
 416  * This iterates all of the pending or delayed thread calls in the group,
 417  * which is really inefficient.
 418  *
 419  * This is deprecated, switch to an allocated thread call instead.
 420  */
 421 extern boolean_t        thread_call_func_cancel(
 422                                                 thread_call_func_t      func,
 423                                                 thread_call_param_t     param,
 424                                                 boolean_t               cancel_all);
 425
 426 /*
 427  * Called on the wake path to adjust the thread callouts running in mach_continuous_time
 428  */
 429 void                            adjust_cont_time_thread_calls(void);
 430
 431 __END_DECLS
 432
 433 #endif  /* XNU_KERNEL_PRIVATE */
 434
 435 #endif  /* _KERN_THREAD_CALL_H_ */