thread_switch

Function - Cause context switch with options.

SYNOPSIS

kern_return_t   thread_switch
                (mach_port_t                         new_thread,
                 int                                     option,
                 mach_msg_timeout_t                        time);

PARAMETERS

new_thread

[in thread send right] Thread to which the processor should switch context.

option

[in scalar] Options applicable to the context switch.

time

[in scalar] Time duration during which the thread should be affected by option.

DESCRIPTION

The thread_switch function provides low-level access to the scheduler's context switching code. new_thread 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.

The option argument specifies the interpretation and use of time. The possible values (from \*L\*O) are:

SWITCH_OPTION_NONE

The time argument is ignored.

SWITCH_OPTION_WAIT

The thread is blocked for the specified time. This wait cannot be canceled by thread_resume; only thread_abort can terminate this wait.

SWITCH_OPTION_DEPRESS

The thread's scheduling attributes are temporarily set so as to provide it with the lowest possible service for duration time. The scheduling depression is aborted when time 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 thread_abort or thread_depress_abort is applied to the current thread. Changing the thread's scheduling attributes (via thread_policy) will not affect this depression.

SWITCH_OPTION_IDLE

This option is similar to SWITCH_OPTION_DEPRESS 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 time. The scheduling depression is aborted when time 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 thread_abort or thread_depress_abort is applied to the current thread. Changing the thread's scheduling attributes (via thread_policy) will not affect this depression.

The minimum time and units of time can be obtained as the min_timeout value from the HOST_SCHED_INFO flavor of host_info.

NOTES

thread_switch 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 new_thread 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 SWITCH_OPTION_WAIT 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.

CAUTIONS

Users should beware of calling thread_switch with an invalid hint (e.g., THREAD_NULL) 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 SWITCH_OPTION_DEPRESS option in this situation is highly recommended.

thread_switch ignores policies. Users relying on the preemption semantics of a fixed time policy should be aware that thread_switch ignores these semantics; it will run the specified new_thread independent of its scheduling attributes and those of any threads that could run instead.

RETURN VALUES

Only generic errors apply.

RELATED INFORMATION

Functions: thread_abort, thread_depress_abort.