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