xref: /xnu-8792.41.9/osfmk/man/thread_switch.html (revision 5c2921b07a2480ab43ec66f5b9e41cb872bc554f) !

<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>.