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