osfmk/man/thread_switch.html

   1 <h2>thread_switch</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Cause context switch with options.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   thread_switch</strong>
   8                 <strong>(mach_port_t</strong>                         <var>new_thread</var>,
   9                  <strong>int</strong>                                     <var>option</var>,
  10                  <strong>mach_msg_timeout_t</strong>                        <var>time</var><strong>);</strong>
  11 </pre>
  12 <h3>PARAMETERS</h3>
  13 <dl>
  14 <p>
  15 <dt> <var>new_thread</var>
  16 <dd>
  17 [in thread send right]
  18 Thread to which the processor should switch
  19 context.
  20 <p>
  21 <dt> <var>option</var>
  22 <dd>
  23 [in scalar]
  24 Options applicable to the context switch.
  25 <p>
  26 <dt> <var>time</var>
  27 <dd>
  28 [in scalar]
  29 Time duration during which the thread should be affected by
  30 <var>option</var>.
  31 </dl>
  32 <h3>DESCRIPTION</h3>
  33 <p>
  34 The <strong>thread_switch</strong> function provides low-level access
  35 to the scheduler's
  36 context switching code.  <var>new_thread</var> is a hint that implements
  37 hand-off scheduling.
  38 The operating system will attempt to switch directly to the new thread
  39 (bypassing the normal logic that selects the next thread to run)
  40 if possible.  Since this is a hint, it may be incorrect; it is ignored if it
  41 doesn't specify a thread on the same host as the current thread or if
  42 the scheduler cannot switch to that thread (i.e.,
  43 not runable or already running on another processor).  In this
  44 case, the normal
  45 logic to select the next thread to run is used; the current thread
  46 may continue
  47 running if there is no other appropriate thread to run.
  48 <p>
  49 The <var>option</var> argument specifies the interpretation and use of <var>time</var>.
  50 The possible values (from \*L<mach/thread_switch.h>\*O) are:
  51 <dl>
  52 <dt> <strong>SWITCH_OPTION_NONE</strong>
  53 <dd>
  54 The <var>time</var> argument is ignored.
  55 <dt> <strong>SWITCH_OPTION_WAIT</strong>
  56 <dd>
  57 The thread is blocked for the specified <var>time</var>.  This wait cannot be
  58 canceled by <strong>thread_resume</strong>;
  59 only <strong>thread_abort</strong> can terminate this wait.
  60 <dt> <strong>SWITCH_OPTION_DEPRESS</strong>
  61 <dd>
  62 The thread's scheduling attributes are temporarily set so as to provide
  63 it with the lowest possible service for duration <var>time</var>.  The scheduling
  64 depression is aborted when <var>time</var> has passed, when the current thread is
  65 next run (either via hand-off scheduling or because the processor set
  66 has nothing better to do), or when <strong>thread_abort</strong> or
  67 <strong>thread_depress_abort</strong> is applied to the current thread.
  68 Changing the thread's scheduling attributes (via <strong>thread_policy</strong>)
  69 will not affect this depression.
  70 <dt> <strong>SWITCH_OPTION_IDLE</strong>
  71 <dd>
  72 This option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the
  73 thread's scheduling attributes are temporarily set so as to place it
  74 at a service level that is below all runnable threads for
  75 duration <var>time</var>.  The scheduling depression is aborted
  76 when <var>time</var> has passed, when the current thread is
  77 next run (either via hand-off scheduling or because the processor set
  78 has nothing better to do), or when <strong>thread_abort</strong> or
  79 <strong>thread_depress_abort</strong> is applied to the current thread.
  80 Changing the thread's scheduling attributes (via <strong>thread_policy</strong>)
  81 will not affect this depression.
  82 </dl>
  83 <p>
  84 The minimum time and units of time can be obtained as the <var>min_timeout</var>
  85 value from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>.
  86 <h3>NOTES</h3>
  87 <p>
  88 <strong>thread_switch</strong> is often called when the current thread
  89 can proceed no further
  90 for some reason; the various options and arguments allow information about
  91 this reason to be transmitted to the kernel.  The <var>new_thread</var>
  92 argument (hand-off
  93 scheduling) is useful when the identity of the thread that must make progress
  94 before the current thread runs again is known.  The <strong>SWITCH_OPTION_WAIT</strong>
  95 option is used when the amount of time that the current thread
  96 must wait before it
  97 can do anything useful can be estimated and is fairly short,
  98 especially when the
  99 identity of the thread for which this thread must wait is not known.
 100 <h3>CAUTIONS</h3>
 101 <p>
 102 Users should beware of calling <strong>thread_switch</strong> with an
 103 invalid hint (e.g., <strong>THREAD_NULL</strong>) and no option.
 104 Because the time-sharing scheduler varies the
 105 priority of threads based on usage, this may result in a waste
 106 of CPU time if the
 107 thread that must be run is of lower priority.  The use of the
 108 <strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended.
 109 <p>
 110 <strong>thread_switch</strong> ignores policies.  Users relying on the
 111 preemption semantics of a
 112 fixed time policy should be aware that <strong>thread_switch</strong>
 113 ignores these semantics;
 114 it will run the specified <var>new_thread</var> independent of its scheduling
 115 attributes and
 116 those of any threads that could run instead.
 117 <h3>RETURN VALUES</h3>
 118 <p>
 119 Only generic errors apply.
 120 <h3>RELATED INFORMATION</h3>
 121 <p>
 122 Functions:
 123 <a href="thread_abort.html"><strong>thread_abort</strong></a>,
 124 <a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>.