thread_switchprovides 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:
- No options, the time argument is ignored.
- The thread is blocked for the specified time (in milliseconds; specifying
0will wait for the next tick). This can be aborted by
- 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_prioritywill not abort the depression). The minimum time and units of time can be obtained as the
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_switchis 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
WAIToption 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
DEPRESSoption 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_switchwith 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
DEPRESSoption in this situation is highly recommended.
thread_switchignores policies. Users relying on the preemption semantics of a fixed time policy should be aware that
thread_switchignores 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_SUCCESSif the call succeeded,
KERN_INVALID_ARGUMENTif thread is not a thread or option is not a recognized option, and
kern_depress_abortfailed because the thread was not depressed.
thread_depress_abortcancels any priority depression for thread caused by a
The function returns
KERN_SUCCESSif the call succeeded and
KERN_INVALID_ARGUMENTif thread is not a valid thread.
The system trap
swtchattempts 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
FALSEif the thread is justified in becoming a resource hog by continuing to spin because there's nothing else useful that the processor could do.
TRUEis returned if the thread should make one more check on the lock and then be a good citizen and really suspend.