xnu-1504.15.3.tar.gz

[apple/xnu.git] / osfmk / man / thread_switch.html

<h2>thread_switch</h2>
<hr>
<p>
<strong>Function</strong> - Cause context switch with options.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   thread_switch</strong>
                <strong>(mach_port_t</strong>                         <var>new_thread</var>,
                 <strong>int</strong>                                     <var>option</var>,
                 <strong>mach_msg_timeout_t</strong>                        <var>time</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>new_thread</var> 
<dd>
[in thread send right]
Thread to which the processor should switch
context.
<p>
<dt> <var>option</var> 
<dd>
[in scalar]
Options applicable to the context switch.
<p>
<dt> <var>time</var> 
<dd>
[in scalar]
Time duration during which the thread should be affected by 
<var>option</var>.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>thread_switch</strong> function provides low-level access
to the scheduler's
context switching code.  <var>new_thread</var> is a hint that implements
hand-off scheduling. 
The operating system will attempt to switch directly to the new thread 
(bypassing the normal logic that selects the next thread to run) 
if possible.  Since this is a hint, it may be incorrect; it is ignored if it 
doesn't specify a thread on the same host as the current thread or if 
the scheduler cannot switch to that thread (i.e., 
not runable or already running on another processor).  In this
case, the normal 
logic to select the next thread to run is used; the current thread
may continue 
running if there is no other appropriate thread to run.
<p>
The <var>option</var> argument specifies the interpretation and use of <var>time</var>.
The possible values (from \*L<mach/thread_switch.h>\*O) are:
<dl>
<dt> <strong>SWITCH_OPTION_NONE</strong>
<dd>
The <var>time</var> argument is ignored.
<dt> <strong>SWITCH_OPTION_WAIT</strong>
<dd>
The thread is blocked for the specified <var>time</var>.  This wait cannot be
canceled by <strong>thread_resume</strong>; 
only <strong>thread_abort</strong> can terminate this wait.
<dt> <strong>SWITCH_OPTION_DEPRESS</strong>
<dd>
The thread's scheduling attributes are temporarily set so as to provide 
it with the lowest possible service for duration <var>time</var>.  The scheduling
depression is aborted when <var>time</var> has passed, when the current thread is 
next run (either via hand-off scheduling or because the processor set 
has nothing better to do), or when <strong>thread_abort</strong> or
<strong>thread_depress_abort</strong> is applied to the current thread.
Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) 
will not affect this depression.
<dt> <strong>SWITCH_OPTION_IDLE</strong>
<dd>
This option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the 
thread's scheduling attributes are temporarily set so as to place it 
at a service level that is below all runnable threads for 
duration <var>time</var>.  The scheduling depression is aborted 
when <var>time</var> has passed, when the current thread is 
next run (either via hand-off scheduling or because the processor set 
has nothing better to do), or when <strong>thread_abort</strong> or
<strong>thread_depress_abort</strong> is applied to the current thread.
Changing the thread's scheduling attributes (via <strong>thread_policy</strong>) 
will not affect this depression.
</dl>
<p>
The minimum time and units of time can be obtained as the <var>min_timeout</var> 
value from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>.
<h3>NOTES</h3>
<p>
<strong>thread_switch</strong> is often called when the current thread
can proceed no further 
for some reason; the various options and arguments allow information about 
this reason to be transmitted to the kernel.  The <var>new_thread</var>
argument (hand-off 
scheduling) is useful when the identity of the thread that must make progress
before the current thread runs again is known.  The <strong>SWITCH_OPTION_WAIT</strong>
option is used when the amount of time that the current thread
must wait before it 
can do anything useful can be estimated and is fairly short,
especially when the 
identity of the thread for which this thread must wait is not known.
<h3>CAUTIONS</h3>
<p>
Users should beware of calling <strong>thread_switch</strong> with an
invalid hint (e.g., <strong>THREAD_NULL</strong>) and no option.  
Because the time-sharing scheduler varies the 
priority of threads based on usage, this may result in a waste
of CPU time if the 
thread that must be run is of lower priority.  The use of the 
<strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended.
<p>
<strong>thread_switch</strong> ignores policies.  Users relying on the
preemption semantics of a 
fixed time policy should be aware that <strong>thread_switch</strong>
ignores these semantics; 
it will run the specified <var>new_thread</var> independent of its scheduling
attributes and 
those of any threads that could run instead.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="thread_abort.html"><strong>thread_abort</strong></a>,
<a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>.