#include <mach/thread_act.h> also included by
<mach/mach.h>mach/thread_act.h
macro_thread_act_user_
#define _thread_act_user_
macrothread_act_MSG_COUNT
#define thread_act_MSG_COUNT 34
functionthread_terminate
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_terminate( thread_act_t target_act )
If building for Sandbox, keep NAME unchanged
Destroy the target thread.
JMM - For legacy reasons this consumes a reference to the
target thread. This will have to change in the future because
we want the interfaces to be able to be defined in more standard
IDLs and transports, and most of them do not support the notion
of reference ownership transfers (just sharing).
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Destroy a thread.
The thread_terminate function kills target_thread.
GNU Mach reference · 7.1.2 Thread Termination · © FSF, GFDL
kern_return_t thread_terminate(thread_t target_thread)
The function thread_terminate destroys the thread specified by target_thread.
The function returns KERN_SUCCESS if the thread has been killed and KERN_INVALID_ARGUMENT if target_thread is not a thread.
functionact_get_state
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t act_get_state( thread_read_t target_act, int flavor, thread_state_t old_state, /* out */ mach_msg_type_number_t *old_stateCnt )
Return the selected state information for the target
thr_act. If the thr_act is currently executing, the results
may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a
list of valid flavors for the target thread.]
functionact_set_state
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t act_set_state( thread_act_t target_act, int flavor, thread_state_t new_state, mach_msg_type_number_t new_stateCnt )
Set the selected state information for the target thread.
If the thread is currently executing, the state change
may be ill-defined.
functionthread_get_state
extern __WATCHOS_PROHIBITED kern_return_t thread_get_state( thread_read_t target_act, thread_state_flavor_t flavor, thread_state_t old_state, /* out */ mach_msg_type_number_t *old_stateCnt )
Backward compatible old-style thread routines.
These have different semantics than the new activation versions.
Return the selected state information for the target
thread. If the thread is currently executing, the results
may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a
list of valid flavors for the target thr_act.]
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Return the execution state for a thread.
The thread_get_state function returns the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state information returned.
The format of the data returned is machine specific; it is defined in \*L \*O.
GNU Mach reference · 7.1.5 Thread Execution · © FSF, GFDL
kern_return_t thread_get_state(thread_t target_thread, int flavor, thread_state_t old_state, mach_msg_type_number_t *old_stateCnt)
The function thread_get_state returns the execution state (e.g. the machine registers) of target_thread as specified by flavor. The old_state is an array of integers that is provided by the caller and returned filled with the specified information. old_stateCnt is input set to the maximum number of integers in old_state and returned equal to the actual number of integers in old_state.
target_thread may not be mach_thread_self().
The definition of the state structures can be found in machine/thread_status.h.
The function returns KERN_SUCCESS if the state has been returned, KERN_INVALID_ARGUMENT if target_thread is not a thread or is mach_thread_self or flavor is unrecognized for this machine. The function returns MIG_ARRAY_TOO_LARGE if the returned state is too large for old_state. In this case, old_state is filled as much as possible and old_stateCnt is set to the number of elements that would have been returned if there were enough room.
functionthread_set_state
extern __WATCHOS_PROHIBITED kern_return_t thread_set_state( thread_act_t target_act, thread_state_flavor_t flavor, thread_state_t new_state, mach_msg_type_number_t new_stateCnt )
Set the selected state information for the target thread.
If the thread is currently executing, the state change
may be ill-defined.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Set the target thread's user-mode execution state.
The thread_set_state function sets the execution state (for example, the machine registers) for target_thread. flavor specifies the type of state to set.
The format of the state to set is machine specific; it is defined in mach/thread_status.h.
GNU Mach reference · 7.1.5 Thread Execution · © FSF, GFDL
kern_return_t thread_set_state(thread_t target_thread, int flavor, thread_state_t new_state, mach_msg_type_number_t new_state_count)
The function thread_set_state sets the execution state (e.g. the machine registers) of target_thread as specified by flavor. The new_state is an array of integers. new_state_count is the number of elements in new_state. The entire set of registers is reset. This will do unpredictable things if target_thread is not suspended.
target_thread may not be mach_thread_self.
The definition of the state structures can be found in machine/thread_status.h.
The function returns KERN_SUCCESS if the state has been set and KERN_INVALID_ARGUMENT if target_thread is not a thread or is mach_thread_self or flavor is unrecognized for this machine.
functionthread_suspend
extern __WATCHOS_PROHIBITED kern_return_t thread_suspend(thread_read_t target_act)
Increment the suspend count for the target thread.
Once this call has completed, the thread will not
execute any further user or meta- instructions.
Once suspended, a thread may not execute again until
its suspend count is zero, and the suspend count
for its task is also zero.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Suspend a thread.
The thread_suspend function increments the suspend count for target_thread and prevents the thread from executing any more user-level instructions.
In this context, a user-level instruction can be either a machine instruction executed in user mode or a system trap instruction, including a page fault. If a thread is currently executing within a system trap, the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, the system trap returns when the thread resumes.
To resume a suspended thread, use thread_resume. If the suspend count is greater than one, thread_resume must be repeated that number of times.
Cautions. Unpredictable results may occur if a program suspends a thread and alters its user state so that its direction is changed upon resuming. Note that the thread_abort function allows a system call to be aborted only if it is progressing in a predictable way.
GNU Mach reference · 7.1.5 Thread Execution · © FSF, GFDL
kern_return_t thread_suspend(thread_t target_thread)
Increments the thread's suspend count and prevents the thread from executing any more user level instructions. In this context a user level instruction is either a machine instruction executed in user mode or a system trap instruction including page faults. Thus if a thread is currently executing within a system trap the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, when the thread is resumed the system trap will return. This could cause unpredictable results if the user did a suspend and then altered the user state of the thread in order to change its direction upon a resume. The call thread_abort is provided to allow the user to abort any system call that is in progress in a predictable way.
The suspend count may become greater than one with the effect that it will take more than one resume call to restart the thread.
The function returns KERN_SUCCESS if the thread has been suspended and KERN_INVALID_ARGUMENT if target_thread is not a thread.
functionthread_resume
extern __WATCHOS_PROHIBITED kern_return_t thread_resume(thread_read_t target_act)
Decrement the suspend count for the target thread,
if that count is not already zero.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Resume a thread.
The thread_resume function decrements the suspend count for target_thread by one. The thread is resumed if its suspend count goes to zero. If the suspend count is still positive, thread_resume must be repeated until the count reaches zero.
Notes. An attempt to lower the suspend count below zero is ignored.
GNU Mach reference · 7.1.5 Thread Execution · © FSF, GFDL
kern_return_t thread_resume(thread_t target_thread)
Decrements the thread's suspend count. If the count becomes zero the thread is resumed. If it is still positive, the thread is left suspended. The suspend count may not become negative.
The function returns KERN_SUCCESS if the thread has been resumed, KERN_FAILURE if the suspend count is already zero and KERN_INVALID_ARGUMENT if target_thread is not a thread.
functionthread_abort
extern __WATCHOS_PROHIBITED kern_return_t thread_abort(thread_act_t target_act)
Cause any user or meta- instructions currently being
executed by the target thread to be aborted. [Meta-
instructions consist of the basic traps for IPC
(e.g., msg_send, msg_receive) and self-identification
(e.g., task_self, thread_self, thread_reply). Calls
described by MiG interfaces are not meta-instructions
themselves.]
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Abort a thread.
The thread_abort function aborts page faults and any message primitive calls in use by target_thread. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes.
If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls.
The basic purpose of thread_abort is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort returns, the target thread will appear to have just returned from the kernel (if it had been in kernel mode).
Notes. By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state.
A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory.
For a thread executing within a system call, thread_abort aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may be completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by thread_set_state, it will not be altered un-predictably by any unexpected system call side effects.
For example, to simulate a POSIX signal, use the following sequence of calls: thread_suspend \(emTo stop the thread. thread_abort \(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. thread_set_state \(emTo modify the thread's user state to simulate a procedure call to the signal handler. thread_resume \(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent.
Cautions. As a rule, do not use thread_abort on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread.
thread_abort will abort any non-atomic operation (such as a multi-page memory_object_data_supply) at an arbitrary point in a non-restartable way. Such problems can be avoided by using thread_abort_safely.
| KERN_EXCEPTION_PROTECTED | The thread is processing a protected exception. |
GNU Mach reference · 7.1.5 Thread Execution · © FSF, GFDL
kern_return_t thread_abort(thread_t target_thread)
The function thread_abort aborts the kernel primitives: mach_msg, msg_send, msg_receive and msg_rpc and page-faults, making the call return a code indicating that it was interrupted. The call is interrupted whether or not the thread (or task containing it) is currently suspended. If it is suspended, the thread receives the interrupt when it is resumed.
A thread will retry an aborted page-fault if its state is not modified before it is resumed. msg_send returns SEND_INTERRUPTED; msg_receive returns RCV_INTERRUPTED; msg_rpc returns either SEND_INTERRUPTED or RCV_INTERRUPTED, depending on which half of the RPC was interrupted.
The main reason for this primitive is to allow one thread to cleanly stop another thread in a manner that will allow the future execution of the target thread to be controlled in a predictable way. thread_suspend keeps the target thread from executing any further instructions at the user level, including the return from a system call. thread_get_state/thread_set_state allows the examination or modification of the user state of a target thread. However, if a suspended thread was executing within a system call, it also has associated with it a kernel state. This kernel state can not be modified by thread_set_state with the result that when the thread is resumed the system call may return changing the user state and possibly user memory. thread_abort aborts the kernel call from the target thread's point of view by resetting the kernel state so that the thread will resume execution at the system call return with the return code value set to one of the interrupted codes. The system call itself will either be entirely completed or entirely aborted, depending on the precise moment at which the abort was received. Thus if the thread's user state has been changed by thread_set_state, it will not be modified by any unexpected system call side effects.
For example to simulate a Unix signal, the following sequence of calls may be used: thread_suspend: Stops the thread. thread_abort: Interrupts any system call in progress, setting the return value to `interrupted'. Since the thread is stopped, it will not return to user code. thread_set_state: Alters thread's state to simulate a procedure call to the signal handler thread_resume: Resumes execution at the signal handler. If the thread's stack has been correctly set up, the thread may return to the interrupted system call. (Of course, the code to push an extra stack frame and change the registers is VERY machine-dependent.)
Calling thread_abort on a non-suspended thread is pretty risky, since it is very difficult to know exactly what system trap, if any, the thread might be executing and whether an interrupt return would cause the thread to do something useful.
The function returns KERN_SUCCESS if the thread received an interrupt and KERN_INVALID_ARGUMENT if target_thread is not a thread.
functionthread_abort_safely
extern __WATCHOS_PROHIBITED kern_return_t thread_abort_safely(thread_act_t target_act)
Cause any user or meta- instructions currently being
executed by the target thread to be aborted so that
they are transparently restartable. This call fails
if the abort would result in a non-restartable condition.
Retry is the caller's responsibility. [Meta-
instructions consist of the basic traps for IPC
(e.g., msg_send, msg_receive) and self-identification
(e.g., task_self, thread_self, thread_reply). Calls
described by MiG interfaces are not meta-instructions
themselves.]
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Abort a thread, restartably.
The thread_abort_safely function aborts page faults and any message primitive calls in use by target_thread. Scheduling depressions and clock sleeps are also aborted. The call returns a code indicating that it was interrupted. The call is interrupted even if the thread (or the task containing it) is suspended. If it is suspended, the thread receives the interrupt when it resumes.
If its state is not modified before it resumes, the thread will retry an aborted page fault. The Mach message trap returns either MACH_SEND_INTERRUPTED or MACH_RCV_INTERRUPTED, depending on whether the send or the receive side was interrupted. Note, though, that the Mach message trap is contained within the mach_msg library routine, which, by default, retries interrupted message calls.
The basic purpose of thread_abort_safely is to let one thread cleanly stop another thread (target_thread). The target thread is stopped in such a manner that its future execution can be controlled in a predictable way. When thread_abort_safely returns (if successful), the target thread will appear to have just returned from the kernel (if it had been in kernel mode).
Notes. By way of comparison, the thread_suspend function keeps the target thread from executing any further instructions at the user level, including the return from a system call. The thread_get_state function returns the thread's user state, while thread_set_state allows modification of the user state.
A problem occurs if a suspended thread had been executing within a system call. In this case, the thread has, not only a user state, but an associated kernel state. (The kernel state cannot be changed with thread_set_state.) As a result, when the thread resumes, the system call can return, producing a change in the user state and, possibly, user memory.
For a thread executing within a system call, thread_abort_safely aborts the kernel call from the thread's point of view. Specifically, it resets the kernel state so that the thread will resume execution at the system call return, with the return code value set to one of the interrupted codes. The system call itself may completed entirely, aborted entirely or be partially completed, depending on when the abort is received. As a result, if the thread's user state has been modified by thread_set_state, it will not be altered un-predictably by any unexpected system call side effects.
For example, to simulate a POSIX signal, use the following sequence of calls: thread_suspend \(emTo stop the thread. thread_abort_safely \(emTo interrupt any system call in progress and set the return value to "interrupted". Because the thread is already stopped, it will not return to user code. thread_set_state \(emTo modify the thread's user state to simulate a procedure call to the signal handler. thread_resume \(emTo resume execution at the signal handler. If the thread's stack is set up correctly, the thread can return to the interrupted system call. Note that the code to push an extra stack frame and change the registers is highly machine dependent.
Cautions. As a rule, do not use thread_abort_safely on a non-suspended thread. This operation is very risky because it is difficult to know which system trap, if any, is executing and whether an interrupt return will result in some useful action by the thread.
thread_abort_safely will not abort any non-atomic operation (such as a multi-page memory_object_data_supply or exception processing) but will return an error instead. The caller of this function must then allow the thread to resume and attempt to abort it later. If the thread must be aborted, even if doing so would abort any non-atomic operations, thread_abort would be used.
| KERN_FAILURE | The thread is in the middle of a non-restartable operation. |
functionthread_depress_abort
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_depress_abort( thread_act_t thread )
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Cancel thread scheduling depression.
The thread_depress_abort function cancels any scheduling depression effective for thread caused by a thread_switch call.
GNU Mach reference · 7.1.6.2 Hand-Off Scheduling · © FSF, GFDL
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.
functionthread_get_special_port
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_get_special_port( thread_inspect_t thr_act, int which_port, mach_port_t *special_port /* out */ )
Returns the current value of the selected special port
associated with the target thread.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Return a send right to the caller-specified special port.
The thread_get_special_port function returns a send right for a special port belonging to thread.
The thread kernel port is a port for which the kernel holds the receive right. The kernel uses this port to identify the thread.
If one thread has a send right for the kernel port of another thread, it can use the port to perform kernel operations for the other thread. Send rights for a kernel port normally are held only by the thread to which the port belongs, or by the task that contains the thread. Using the mach_msg function, however, any thread can pass a send right for its kernel port to another thread.
GNU Mach reference · 7.1.7 Thread Special Ports · © FSF, GFDL
kern_return_t thread_get_special_port(thread_t thread, int which_port, mach_port_t *special_port)
The function thread_get_special_port returns send rights to one of a set of special ports for the thread specified by thread.
The possible values for which_port are THREAD_KERNEL_PORT and THREAD_EXCEPTION_PORT. A thread also has access to its task's special ports.
The function returns KERN_SUCCESS if the port was returned and KERN_INVALID_ARGUMENT if thread is not a thread or which_port is an invalid port selector.
functionthread_set_special_port
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_set_special_port( thread_act_t thr_act, int which_port, mach_port_t special_port )
Set one of the special ports associated with the
target thread.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Set caller-specified special port belonging to the target thread.
The thread_set_special_port function sets a special port belonging to thread.
GNU Mach reference · 7.1.7 Thread Special Ports · © FSF, GFDL
kern_return_t thread_set_special_port(thread_t thread, int which_port, mach_port_t special_port)
The function thread_set_special_port sets one of a set of special ports for the thread specified by thread.
The possible values for which_port are THREAD_KERNEL_PORT and THREAD_EXCEPTION_PORT. A thread also has access to its task's special ports.
The function returns KERN_SUCCESS if the port was set and KERN_INVALID_ARGUMENT if thread is not a thread or which_port is an invalid port selector.
functionthread_info
extern kern_return_t thread_info( thread_inspect_t target_act, thread_flavor_t flavor, thread_info_t thread_info_out, /* out */ mach_msg_type_number_t *thread_info_outCnt )
Returns information about the target thread.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Return information about a thread.
The thread_info function returns an information structure of type flavor.
Notes. At any given time, a thread has only one scheduling policy in effect for it. Thus, only one of the scheduling information structures will be valid, that so indicated by the policy value returned by THREAD_BASIC_INFO.
GNU Mach reference · 7.1.3 Thread Information · © FSF, GFDL
kern_return_t thread_info(thread_t target_thread, int flavor, thread_info_t thread_info, mach_msg_type_number_t *thread_infoCnt)
The function thread_info returns the selected information array for a thread, as specified by flavor.
thread_info is an array of integers that is supplied by the caller and returned filled with specified information. thread_infoCnt is supplied as the maximum number of integers in thread_info. On return, it contains the actual number of integers in thread_info. The maximum number of integers returned by any flavor is THREAD_INFO_MAX.
The type of information returned is defined by flavor, which can be one of the following: THREAD_BASIC_INFOThe function returns basic information about the thread, as defined by thread_basic_info_t. This includes the user and system time, the run state, and scheduling priority. The number of integers returned is THREAD_BASIC_INFO_COUNT. THREAD_SCHED_INFOThe function returns information about the scheduling policy for the thread as defined by thread_sched_info_t. The number of integers returned is THREAD_SCHED_INFO_COUNT.
The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_thread is not a thread or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for thread_info. In this case, thread_info is filled as much as possible and thread_infoCnt is set to the number of elements that would have been returned if there were enough room.
functionthread_set_exception_ports
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_set_exception_ports( thread_act_t thread, exception_mask_t exception_mask, mach_port_t new_port, exception_behavior_t behavior, thread_state_flavor_t new_flavor )
Set an exception handler for a thread on one or more exception types
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Set exception ports for a thread.
The thread_set_exception_ports function sets a specified set of exception ports belonging to thread.
Notes. If the value of the EXC_MACH_SYSCALL exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception.
A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (thread_abort).
functionthread_get_exception_ports
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_get_exception_ports( thread_act_t thread, exception_mask_t exception_mask, exception_mask_array_t masks, /* out */ mach_msg_type_number_t *masksCnt, exception_handler_array_t old_handlers, /* out */ exception_behavior_array_t old_behaviors, /* out */ exception_flavor_array_t old_flavors /* out */ )
Lookup some of the old exception handlers for a thread
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Return a send right to an exception port.
The thread_get_exception_ports function returns send rights for a specified set of exception ports belonging to thread. The call returns a set of quadruples for each unique set of in effect for the thread where the exception type mask indicates for which exception types the other values apply.
| KERN_EXCEPTION_PROTECTED | One of the requested exception ports is protected and cannot be returned. |
functionthread_swap_exception_ports
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_swap_exception_ports( thread_act_t thread, exception_mask_t exception_mask, mach_port_t new_port, exception_behavior_t behavior, thread_state_flavor_t new_flavor, exception_mask_array_t masks, /* out */ mach_msg_type_number_t *masksCnt, exception_handler_array_t old_handlers, /* out */ exception_behavior_array_t old_behaviors, /* out */ exception_flavor_array_t old_flavors /* out */ )
Set an exception handler for a thread on one or more exception types.
At the same time, return the previously defined exception handlers for
those types.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Swap exception ports for a thread.
The thread_swap_exception_ports function sets a specified set of exception ports belonging to thread, returning the old set.
Notes. If the value of the EXC_MACH_SYSCALL exception class exception port is the host name port, Mach kernel traps are executed by the kernel as expected; any other value causes the attempted execution of these system call numbers to be considered an exception.
A "protected" exception port is one which cannot be fetched and for which exception processing cannot be aborted (thread_abort).
| KERN_EXCEPTION_PROTECTED | One of the requested exception ports is protected and cannot be returned. |
functionthread_policy
extern kern_return_t thread_policy( thread_act_t thr_act, policy_t policy, policy_base_t base, mach_msg_type_number_t baseCnt, boolean_t set_limit )
OBSOLETE interface.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Set target thread's scheduling policy state.
The thread_policy function sets the scheduling policy to be applied to thread. policy must be a scheduling policy currently "enabled" for the thread's assigned processor set.
| KERN_INVALID_POLICY | The processor set to which thread is currently assigned does not currently enable policy. |
| KERN_POLICY_LIMIT | The specified scheduling attributes exceeds the thread's limits. |
GNU Mach reference · 7.1.6.3 Scheduling Policy · © FSF, GFDL
kern_return_t thread_policy(thread_t thread, int policy, int data)
The function thread_policy changes the scheduling policy for thread to policy.
data is policy-dependent scheduling information. There are currently two supported policies: POLICY_TIMESHARE and POLICY_FIXEDPRI defined in mach/policy.h; this file is included by mach.h. data is meaningless for timesharing, but is the quantum to be used (in milliseconds) for the fixed priority policy. To be meaningful, this quantum must be a multiple of the basic system quantum (min_quantum) which can be obtained from host_info. The system will always round up to the next multiple of the quantum.
Processor sets may restrict the allowed policies, so this call will fail if the processor set to which thread is currently assigned does not permit policy.
The function returns KERN_SUCCESS if the call succeeded. KERN_INVALID_ARGUMENT if thread is not a thread or policy is not a recognized policy, and KERN_FAILURE if the processor set to which thread is currently assigned does not permit policy.
functionthread_policy_set
extern kern_return_t thread_policy_set( thread_act_t thread, thread_policy_flavor_t flavor, thread_policy_t policy_info, mach_msg_type_number_t policy_infoCnt )
Set/get policy information for a thread.
(Approved Mac OS X microkernel interface)
functionthread_policy_get
extern kern_return_t thread_policy_get( thread_inspect_t thread, thread_policy_flavor_t flavor, thread_policy_t policy_info, /* out */ mach_msg_type_number_t *policy_infoCnt, boolean_t *get_default /* inout */ )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/thread_policy.c
Returns scheduling policy information for the target thread. flavor selects the information, e.g. THREAD_EXTENDED_POLICY (whether the thread is timesharing) or THREAD_TIME_CONSTRAINT_POLICY (real-time period, computation, and constraint parameters); policy_infoCnt gives the size of the buffer in integers and is updated on return. If get_default is TRUE on input, the system default for that flavor is returned; on output get_default is set TRUE if the information returned is the default (e.g. the flavor does not match the thread's current policy). Returns KERN_INVALID_ARGUMENT for a null thread or unknown flavor and KERN_TERMINATED if the thread has terminated.
functionthread_sample
extern kern_return_t thread_sample(thread_act_t thread, mach_port_t reply)
Removed from the kernel.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Perform periodic PC sampling for a thread.
The thread_sample function causes the program counter (PC) of the specified sample_thread to be sampled periodically (whenever the thread happens to be running at the time of the kernel's "hardclock" interrupt). The set of PC sample values obtained are saved in buffers which are sent to the specified reply_port in receive_samples messages.
functionetap_trace_thread
extern kern_return_t etap_trace_thread(thread_act_t target_act, boolean_t trace_status)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/mach/thread_act.defs
Obsolete; removed from the kernel. Historically enabled or disabled ETAP (Event Trace Analysis Package) event tracing for the target thread. The kernel no longer implements the routine (it is skipped in the MIG server), so calls fail with MIG_BAD_ID.
functionthread_assign
extern kern_return_t thread_assign(thread_act_t thread, processor_set_t new_set)
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Assign a thread to a processor set.
The thread_assign function assigns thread to the set processor_set. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified.
functionthread_assign_default
extern kern_return_t thread_assign_default(thread_act_t thread)
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Assign a thread to the default processor set.
The thread_assign_default function assigns thread to the default processor set. After the assignment is completed, the thread executes only on processors that are assigned to that processor set. Any previous assignment of the thread is nullified.
Notes. This variant of thread_assign exists because the control port for the default processor set is privileged, and therefore not available to most tasks.
functionthread_get_assignment
extern kern_return_t thread_get_assignment( thread_inspect_t thread, processor_set_name_t *assigned_set /* out */ )
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Return the processor set to which a thread is assigned.
The thread_get_assignment function returns the name port to the processor set to which thread is currently assigned. This port can only be used to obtain information about the processor set.
functionthread_set_policy
extern kern_return_t thread_set_policy( thread_act_t thr_act, processor_set_t pset, policy_t policy, policy_base_t base, mach_msg_type_number_t baseCnt, policy_limit_t limit, mach_msg_type_number_t limitCnt )
OBSOLETE interface.
CMU/MIT Mach reference · manual page · © Carnegie Mellon
Set target thread's scheduling policy state. (Protected Interface.)
The thread_set_policy function sets the scheduling attributes, both base and limit, for thread. policy may be any policy implemented by the processor set whether or not it is enabled.
| KERN_INVALID_PROCESSOR_SET | processor_set is not the thread's processor set control port. |
functionthread_get_mach_voucher
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_get_mach_voucher( thread_read_t thr_act, mach_voucher_selector_t which, ipc_voucher_t *voucher /* out */ )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/thread.c
Returns a reference to the Mach voucher currently adopted by the target thread, or IPC_VOUCHER_NULL if the thread has none. The which selector is presently ignored; there is no distinction between the current and effective voucher. Returns KERN_INVALID_ARGUMENT for a null thread. The caller is responsible for releasing the returned voucher reference.
functionthread_set_mach_voucher
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_set_mach_voucher( thread_act_t thr_act, ipc_voucher_t voucher )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/thread.c
Adopts the specified voucher on the target thread, taking a reference on it and releasing the reference held on any previously adopted voucher; the thread's bank ledger and thread group are updated to those named by the new voucher. The target must be the calling thread or a thread that has not yet been started; otherwise KERN_INVALID_ARGUMENT is returned, as it is for a null thread.
functionthread_swap_mach_voucher
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_swap_mach_voucher( thread_act_t thr_act, ipc_voucher_t new_voucher, ipc_voucher_t *old_voucher /* inout */ )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/thread.c
No longer supported. Historically adopted new_voucher on the target thread and returned the previously adopted voucher in old_voucher as an atomic swap. The routine now returns KERN_NOT_SUPPORTED unconditionally, releasing the reference passed in old_voucher.
functionthread_convert_thread_state
extern kern_return_t thread_convert_thread_state( thread_act_t thread, int direction, thread_state_flavor_t flavor, thread_state_t in_state, mach_msg_type_number_t in_stateCnt, thread_state_t out_state, /* out */ mach_msg_type_number_t *out_stateCnt )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/thread_act.c
Converts thread state of the given flavor between the user representations of two threads; on arm64e this re-signs pointer-authentication (PAC) signed register values, so state captured from one thread can be used with thread_set_state on another. direction is THREAD_CONVERT_THREAD_STATE_TO_SELF (convert state of thread for use by the calling thread) or THREAD_CONVERT_THREAD_STATE_FROM_SELF (convert the caller's state for use with thread). in_state is validated against the source thread and rewritten into out_state; out_stateCnt gives the buffer size in integers and is updated on return. Returns KERN_INVALID_ARGUMENT for a bad direction or null thread and KERN_INSUFFICIENT_BUFFER_SIZE if the output buffer is too small.
functionthread_get_exception_ports_info
extern kern_return_t thread_get_exception_ports_info( mach_port_t port, exception_mask_t exception_mask, exception_mask_array_t masks, /* out */ mach_msg_type_number_t *masksCnt, exception_handler_info_array_t old_handlers_info, /* out */ exception_behavior_array_t old_behaviors, /* out */ exception_flavor_array_t old_flavors /* out */ )
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/ipc_tt.c
Variant of thread_get_exception_ports that returns information about the thread's exception handlers instead of send rights to them, and therefore requires only a thread read port. For each exception type selected by exception_mask, the registered handler is reported as an ipc_info_port_t pair of obfuscated identifiers for the handler port and its receiving task, along with the handler's behavior and thread-state flavor; entries with identical port, behavior, and flavor are coalesced, with masks giving the exception types each entry covers. masksCnt gives the array capacity on input and the number of entries on output. Returns KERN_INVALID_ARGUMENT if the port does not name a thread.
functionthread_adopt_exception_handler
extern __TVOS_PROHIBITED __WATCHOS_PROHIBITED kern_return_t thread_adopt_exception_handler( thread_t thread, mach_port_t exc_port, exception_mask_t exc_mask, exception_behavior_t behavior_mask, thread_state_flavor_t flavor_mask )
Calls thread_set_exception_ports on thread using a previously registered
hardened exception handler. Only one hardened exception handler is allowed
per task.
functionthread_suspend2
extern __WATCHOS_PROHIBITED kern_return_t thread_suspend2( thread_read_t target_act, mach_port_t *suspend_token /* out */ )
New thread suspend interface that returns a suspend token
functionthread_resume2
extern __WATCHOS_PROHIBITED kern_return_t thread_resume2(mach_port_t suspend_token)
New thread resume interface that takes a suspend token
macrosubsystem_to_name_map_thread_act
#define subsystem_to_name_map_thread_act { "thread_terminate", 3600 },
{ "act_get_state", 3601 },
{ "act_set_state", 3602 },
{ "thread_get_state", 3603 },
{ "thread_set_state", 3604 },
{ "thread_suspend", 3605 },
{ "thread_resume", 3606 },
{ "thread_abort", 3607 },
{ "thread_abort_safely", 3608 },
{ "thread_depress_abort", 3609 },
{ "thread_get_special_port", 3610 },
{ "thread_set_special_port", 3611 },
{ "thread_info", 3612 },
{ "thread_set_exception_ports", 3613 },
{ "thread_get_exception_ports", 3614 },
{ "thread_swap_exception_ports", 3615 },
{ "thread_policy", 3616 },
{ "thread_policy_set", 3617 },
{ "thread_policy_get", 3618 },
{ "thread_sample", 3619 },
{ "etap_trace_thread", 3620 },
{ "thread_assign", 3621 },
{ "thread_assign_default", 3622 },
{ "thread_get_assignment", 3623 },
{ "thread_set_policy", 3624 },
{ "thread_get_mach_voucher", 3625 },
{ "thread_set_mach_voucher", 3626 },
{ "thread_swap_mach_voucher", 3627 },
{ "thread_convert_thread_state", 3628 },
{ "thread_get_exception_ports_info", 3630 },
{ "thread_adopt_exception_handler", 3631 },
{ "thread_suspend2", 3632 },
{ "thread_resume2", 3633 }