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