-<h2>thread_switch</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Cause context switch with options.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_switch</strong>
\r <strong>(mach_port_t</strong> <var>new_thread</var>,
\r <strong>int</strong> <var>option</var>,
\r <strong>mach_msg_timeout_t</strong> <var>time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>new_thread</var>
\r<dd>
\r[in thread send right]
\rThread to which the processor should switch
\rcontext.
\r<p>
\r<dt> <var>option</var>
\r<dd>
\r[in scalar]
\rOptions applicable to the context switch.
\r<p>
\r<dt> <var>time</var>
\r<dd>
\r[in scalar]
\rTime duration during which the thread should be affected by
\r<var>option</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_switch</strong> function provides low-level access
\rto the scheduler's
\rcontext switching code. <var>new_thread</var> is a hint that implements
\rhand-off scheduling.
\rThe operating system will attempt to switch directly to the new thread
\r(bypassing the normal logic that selects the next thread to run)
\rif possible. Since this is a hint, it may be incorrect; it is ignored if it
\rdoesn't specify a thread on the same host as the current thread or if
\rthe scheduler cannot switch to that thread (i.e.,
\rnot runable or already running on another processor). In this
\rcase, the normal
\rlogic to select the next thread to run is used; the current thread
\rmay continue
\rrunning if there is no other appropriate thread to run.
\r<p>
\rThe <var>option</var> argument specifies the interpretation and use of <var>time</var>.
\rThe possible values (from \*L<mach/thread_switch.h>\*O) are:
\r<dl>
\r<dt> <strong>SWITCH_OPTION_NONE</strong>
\r<dd>
\rThe <var>time</var> argument is ignored.
\r<dt> <strong>SWITCH_OPTION_WAIT</strong>
\r<dd>
\rThe thread is blocked for the specified <var>time</var>. This wait cannot be
\rcanceled by <strong>thread_resume</strong>;
\ronly <strong>thread_abort</strong> can terminate this wait.
\r<dt> <strong>SWITCH_OPTION_DEPRESS</strong>
\r<dd>
\rThe thread's scheduling attributes are temporarily set so as to provide
\rit with the lowest possible service for duration <var>time</var>. The scheduling
\rdepression is aborted when <var>time</var> has passed, when the current thread is
\rnext run (either via hand-off scheduling or because the processor set
\rhas nothing better to do), or when <strong>thread_abort</strong> or
\r<strong>thread_depress_abort</strong> is applied to the current thread.
\rChanging the thread's scheduling attributes (via <strong>thread_policy</strong>)
\rwill not affect this depression.
\r<dt> <strong>SWITCH_OPTION_IDLE</strong>
\r<dd>
\rThis option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the
\rthread's scheduling attributes are temporarily set so as to place it
\rat a service level that is below all runnable threads for
\rduration <var>time</var>. The scheduling depression is aborted
\rwhen <var>time</var> has passed, when the current thread is
\rnext run (either via hand-off scheduling or because the processor set
\rhas nothing better to do), or when <strong>thread_abort</strong> or
\r<strong>thread_depress_abort</strong> is applied to the current thread.
\rChanging the thread's scheduling attributes (via <strong>thread_policy</strong>)
\rwill not affect this depression.
\r</dl>
\r<p>
\rThe minimum time and units of time can be obtained as the <var>min_timeout</var>
\rvalue from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>.
\r<h3>NOTES</h3>
\r<p>
\r<strong>thread_switch</strong> is often called when the current thread
\rcan proceed no further
\rfor some reason; the various options and arguments allow information about
\rthis reason to be transmitted to the kernel. The <var>new_thread</var>
\rargument (hand-off
\rscheduling) is useful when the identity of the thread that must make progress
\rbefore the current thread runs again is known. The <strong>SWITCH_OPTION_WAIT</strong>
\roption is used when the amount of time that the current thread
\rmust wait before it
\rcan do anything useful can be estimated and is fairly short,
\respecially when the
\ridentity of the thread for which this thread must wait is not known.
\r<h3>CAUTIONS</h3>
\r<p>
\rUsers should beware of calling <strong>thread_switch</strong> with an
\rinvalid hint (e.g., <strong>THREAD_NULL</strong>) and no option.
\rBecause the time-sharing scheduler varies the
\rpriority of threads based on usage, this may result in a waste
\rof CPU time if the
\rthread that must be run is of lower priority. The use of the
\r<strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended.
\r<p>
\r<strong>thread_switch</strong> ignores policies. Users relying on the
\rpreemption semantics of a
\rfixed time policy should be aware that <strong>thread_switch</strong>
\rignores these semantics;
\rit will run the specified <var>new_thread</var> independent of its scheduling
\rattributes and
\rthose of any threads that could run instead.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>.
\r\ No newline at end of file
+<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>.
projects / apple / xnu.git / blobdiff