— Function: kern_return_t thread_switch (thread_t new_thread, int option, int time)

The function thread_switch 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 that thread can't be switched to (i.e., not runnable or already running on another processor or giving a plainly invalid hint, such as MACH_PORT_NULL). 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.

Options for option are defined in mach/thread_switch.h and specify the interpretation of time. The possible values for option are:

SWITCH_OPTION_NONE

No options, the time argument is ignored.

SWITCH_OPTION_WAIT

The thread is blocked for the specified time (in milliseconds; specifying 0 will wait for the next tick). This can be aborted by thread_abort.

SWITCH_OPTION_DEPRESS

The thread's priority is depressed to the lowest possible value for the specified time. This can be aborted by thread_depress_abort. This depression is independent of operations that change the thread's priority (e.g. thread_priority will not abort the depression). The minimum time and units of time can be obtained as the min_timeout value from host_info. The depression is also aborted when the current thread is next run (either via hand-off scheduling or because the processor set has nothing better to do).

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 (handoff scheduling) is useful when the identity of the thread that must make progress before the current thread runs again is known. The 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 long. The DEPRESS option is used when the amount of time that must be waited is fairly short, especially when the identity of the thread that is being waited for is not known.

Users should beware of calling thread_switch with an invalid hint (e.g. MACH_PORT_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 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 priority and the priority of any other threads that could be run instead.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if thread is not a thread or option is not a recognized option, and KERN_FAILURE if kern_depress_abort failed because the thread was not depressed.

— Function: kern_return_t thread_depress_abort (thread_t thread)

The function thread_depress_abort cancels any priority depression for thread caused by a swtch_pri or thread_switch call.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if thread is not a valid thread.

— Function: boolean_t swtch ()

The system trap swtch attempts to switch the current thread off the processor. The return value indicates if more than the current thread is running in the processor set. This is useful for lock management routines.

The call returns FALSE if the thread is justified in becoming a resource hog by continuing to spin because there's nothing else useful that the processor could do. TRUE is returned if the thread should make one more check on the lock and then be a good citizen and really suspend.

— Function: boolean_t swtch_pri (int priority)

The system trap swtch_pri attempts to switch the current thread off the processor as swtch does, but depressing the priority of the thread to the minimum possible value during the time. priority is not used currently.

The return value is as for swtch.