7. Threads and Tasks

7.1 Thread Interface

Data type: thread_t

This is a mach_port_t and used to hold the port name of a thread port that represents the thread. Manipulations of the thread are implemented as remote procedure calls to the thread port. A thread can get a port to itself with the mach_thread_self system call.

7.1.1 Thread Creation

Function: kern_return_t thread_create (task_t parent_task, thread_t *child_thread)

The function thread_create creates a new thread within the task specified by parent_task. The new thread has no processor state, and has a suspend count of 1. To get a new thread to run, first thread_create is called to get the new thread's identifier, (child_thread). Then thread_set_state is called to set a processor state, and finally thread_resume is called to get the thread scheduled to execute.

When the thread is created send rights to its thread kernel port are given to it and returned to the caller in child_thread. The new thread's exception port is set to MACH_PORT_NULL.

The function returns KERN_SUCCESS if a new thread has been created, KERN_INVALID_ARGUMENT if parent_task is not a valid task and KERN_RESOURCE_SHORTAGE if some critical kernel resource is not available.

7.1.2 Thread Termination

Function: 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.

7.1.3 Thread Information

Function: thread_t mach_thread_self ()

The mach_thread_self system call returns the calling thread's thread port.

mach_thread_self has an effect equivalent to receiving a send right for the thread port. mach_thread_self returns the name of the send right. In particular, successive calls will increase the calling task's user-reference count for the send right.

As a special exception, the kernel will overrun the user reference count of the thread name port, so that this function can not fail for that reason. Because of this, the user should not deallocate the port right if an overrun might have happened. Otherwise the reference count could drop to zero and the send right be destroyed while the user still expects to be able to use it. As the kernel does not make use of the number of extant send rights anyway, this is safe to do (the thread port itself is not destroyed, even when there are no send rights anymore).

The function returns MACH_PORT_NULL if a resource shortage prevented the reception of the send right or if the thread port is currently null and MACH_PORT_DEAD if the thread port is currently dead.

Function: 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_INFO

The 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_INFO

The function returns information about the schduling 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.

Data type: struct thread_basic_info

This structure is returned in thread_info by the thread_info function and provides basic information about the thread. You can cast a variable of type thread_info_t to a pointer of this type if you provided it as the thread_info parameter for the THREAD_BASIC_INFO flavor of thread_info. It has the following members:

time_value_t user_time

user run time

time_value_t system_time

system run time

int cpu_usage

Scaled cpu usage percentage. The scale factor is TH_USAGE_SCALE.

int base_priority

The base scheduling priority of the thread.

int cur_priority

The current scheduling priority of the thread.

integer_t run_state

The run state of the thread. The possible vlues of this field are:

TH_STATE_RUNNING

The thread is running normally.

TH_STATE_STOPPED

The thread is suspended.

TH_STATE_WAITING

The thread is waiting normally.

TH_STATE_UNINTERRUPTIBLE

The thread is in an uninterruptible wait.

TH_STATE_HALTED

The thread is halted at a clean point.

flags

Various flags. The possible values of this field are:

TH_FLAGS_SWAPPED

The thread is swapped out.

TH_FLAGS_IDLE

The thread is an idle thread.

int suspend_count

The suspend count for the thread.

int sleep_time

The number of seconds that the thread has been sleeping.

time_value_t creation_time

The time stamp of creation.

Data type: thread_basic_info_t

This is a pointer to a struct thread_basic_info.

Data type: struct thread_sched_info

This structure is returned in thread_info by the thread_info function and provides schedule information about the thread. You can cast a variable of type thread_info_t to a pointer of this type if you provided it as the thread_info parameter for the THREAD_SCHED_INFO flavor of thread_info. It has the following members:

int policy

The scheduling policy of the thread, 7.1.6.3 Scheduling Policy.

integer_t data

Policy-dependent scheduling information, 7.1.6.3 Scheduling Policy.

int base_priority

The base scheduling priority of the thread.

int max_priority

The maximum scheduling priority of the thread.

int cur_priority

The current scheduling priority of the thread.

int depressed

TRUE if the thread is depressed.

int depress_priority

The priority the thread was depressed from.

Data type: thread_sched_info_t

This is a pointer to a struct thread_sched_info.

7.1.4 Thread Settings

Function: kern_return_t thread_wire (host_priv_t host_priv, thread_t thread, boolean_t wired)

The function thread_wire controls the VM privilege level of the thread thread. A VM-privileged thread never waits inside the kernel for memory allocation from the kernel's free list of pages or for allocation of a kernel stack.

Threads that are part of the default pageout path should be VM-privileged, to prevent system deadlocks. Threads that are not part of the default pageout path should not be VM-privileged, to prevent the kernel's free list of pages from being exhausted.

The functions returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if host_priv or thread was invalid.

The thread_wire call is actually an RPC to host_priv, normally a send right for a privileged host port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

7.1.5 Thread Execution

Function: 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 supend within the kernel code. In either case, when the thread is resumed the system trap will return. This could cause unpredictible 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.

Function: kern_return_t thread_resume (thread_t target_thread)

Decrements the threads'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.

Function: 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 supsended, the thread receives the interupt 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:

1. thread_suspend: Stops the thread.

2. 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.

3. thread_set_state: Alters thread's state to simulate a procedure call to the signal handler

4. 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.

Function: 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 unrecogized 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.

Function: 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 unrecogized for this machine.

7.1.6 Scheduling

7.1.6.1 Thread Priority

Threads have three priorities associated with them by the system, a priority, a maximum priority, and a scheduled priority. The scheduled priority is used to make scheduling decisions about the thread. It is determined from the priority by the policy (for timesharing, this means adding an increment derived from cpu usage). The priority can be set under user control, but may never exceed the maximum priority. Changing the maximum priority requires presentation of the control port for the thread's processor set; since the control port for the default processor set is privileged, users cannot raise their maximum priority to unfairly compete with other users on that set. Newly created threads obtain their priority from their task and their max priority from the thread.

Function: kern_return_t thread_priority (thread_t thread, int prority, boolean_t set_max)

The function thread_priority changes the priority and optionally the maximum priority of thread. Priorities range from 0 to 31, where lower numbers denote higher priorities. If the new priority is higher than the priority of the current thread, preemption may occur as a result of this call. The maximum priority of the thread is also set if set_max is TRUE. This call will fail if priority is greater than the current maximum priority of the thread. As a result, this call can only lower the value of a thread's maximum priority.

The functions returns KERN_SUCCESS if the operation completed successfully, KERN_INVALID_ARGUMENT if thread is not a thread or priority is out of range (not in 0..31), and KERN_FAILURE if the requested operation would violate the thread's maximum priority (thread_priority).

Function: kern_return_t thread_max_priority (thread_t thread, processor_set_t processor_set, int priority)

The function thread_max_priority changes the maximum priority of the thread. Because it requires presentation of the corresponding processor set port, this call can reset the maximum priority to any legal value.

The functions returns KERN_SUCCESS if the operation completed successfully, KERN_INVALID_ARGUMENT if thread is not a thread or processor_set is not a control port for a processor set or priority is out of range (not in 0..31), and KERN_FAILURE if the thread is not assigned to the processor set whose control port was presented.

7.1.6.2 Hand-Off Scheduling

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 (by passing 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). 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. 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 indepent 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.

7.1.6.3 Scheduling Policy

Function: 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.

7.1.7 Thread Special Ports

Function: 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.

Function: kern_return_t thread_get_kernel_port (thread_t thread, mach_port_t *kernel_port)

The function thread_get_kernel_port is equivalent to the function thread_get_special_port with the which_port argument set to THREAD_KERNEL_PORT.

Function: kern_return_t thread_get_exception_port (thread_t thread, mach_port_t *exception_port)

The function thread_get_exception_port is equivalent to the function thread_get_special_port with the which_port argument set to THREAD_EXCEPTION_PORT.

Function: 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.

Function: kern_return_t thread_set_kernel_port (thread_t thread, mach_port_t kernel_port)

The function thread_set_kernel_port is equivalent to the function thread_set_special_port with the which_port argument set to THREAD_KERNEL_PORT.

Function: kern_return_t thread_set_exception_port (thread_t thread, mach_port_t exception_port)

The function thread_set_exception_port is equivalent to the function thread_set_special_port with the which_port argument set to THREAD_EXCEPTION_PORT.

7.1.8 Exceptions

Function: kern_return_t catch_exception_raise (mach_port_t exception_port, thread_t thread, task_t task, int exception, int code, int subcode)

XXX Fixme

Function: kern_return_t exception_raise (mach_port_t exception_port, mach_port_t thread, mach_port_t task, integer_t exception, integer_t code, integer_t subcode)

XXX Fixme

Function: kern_return_t evc_wait (unsigned int event)

The system trap evc_wait makes the calling thread wait for the event specified by event.

The call returns KERN_SUCCESS if the event has occured, KERN_NO_SPACE if another thread is waiting for the same event and KERN_INVALID_ARGUMENT if the event object is invalid.

7.2 Task Interface

Data type: task_t

This is a mach_port_t and used to hold the port name of a task port that represents the thread. Manipulations of the task are implemented as remote procedure calls to the task port. A task can get a port to itself with the mach_task_self system call.

The task port name is also used to identify the task's IPC space (see section 4.3 Port Manipulation Interface) and the task's virtual memory map (see section 5. Virtual Memory Interface).

7.2.1 Task Creation

Function: kern_return_t task_create (task_t parent_task, boolean_t inherit_memory, task_t *child_task)

The function task_create creates a new task from parent_task; the resulting task (child_task) acquires shared or copied parts of the parent's address space (see vm_inherit). The child task initially contains no threads.

If inherit_memory is set, the child task's address space is built from the parent task according to its memory inheritance values; otherwise, the child task is given an empty address space.

The child task gets the three special ports created or copied for it at task creation. The TASK_KERNEL_PORT is created and send rights for it are given to the child and returned to the caller. The TASK_BOOTSTRAP_PORT and the TASK_EXCEPTION_PORT are inherited from the parent task. The new task can get send rights to these ports with the call task_get_special_port.

The function returns KERN_SUCCESS if a new task has been created, KERN_INVALID_ARGUMENT if parent_task is not a valid task port and KERN_RESOURCE_SHORTAGE if some critical kernel resource is unavailable.

7.2.2 Task Termination

Function: kern_return_t task_terminate (task_t target_task)

The function task_terminate destroys the task specified by target_task and all its threads. All resources that are used only by this task are freed. Any port to which this task has receive and ownership rights is destroyed.

The function returns KERN_SUCCESS if the task has been killed, KERN_INVALID_ARGUMENT if target_task is not a task.

7.2.3 Task Information

Function: task_t mach_task_self ()

The mach_task_self system call returns the calling thread's task port.

mach_task_self has an effect equivalent to receiving a send right for the task port. mach_task_self returns the name of the send right. In particular, successive calls will increase the calling task's user-reference count for the send right.

As a special exception, the kernel will overrun the user reference count of the task name port, so that this function can not fail for that reason. Because of this, the user should not deallocate the port right if an overrun might have happened. Otherwise the reference count could drop to zero and the send right be destroyed while the user still expects to be able to use it. As the kernel does not make use of the number of extant send rights anyway, this is safe to do (the task port itself is not destroyed, even when there are no send rights anymore).

The funcion returns MACH_PORT_NULL if a resource shortage prevented the reception of the send right, MACH_PORT_NULL if the task port is currently null, MACH_PORT_DEAD if the task port is currently dead.

Function: kern_return_t task_threads (task_t target_task, thread_array_t *thread_list, mach_msg_type_number_t *thread_count)

The function task_threads gets send rights to the kernel port for each thread contained in target_task. thread_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task is not a task.

Function: kern_return_t task_info (task_t target_task, int flavor, task_info_t task_info, mach_msg_type_number_t *task_info_count)

The function task_info returns the selected information array for a task, as specified by flavor. task_info is an array of integers that is supplied by the caller, and filled with specified information. task_info_count is supplied as the maximum number of integers in task_info. On return, it contains the actual number of integers in task_info. The maximum number of integers returned by any flavor is TASK_INFO_MAX.

The type of information returned is defined by flavor, which can be one of the following:

TASK_BASIC_INFO

The function returns basic information about the task, as defined by task_basic_info_t. This includes the user and system time and memory consumption. The number of integers returned is TASK_BASIC_INFO_COUNT.

TASK_EVENTS_INFO

The function returns information about events for the task as defined by thread_sched_info_t. This includes statistics about virtual memory and IPC events like pageouts, pageins and messages sent and received. The number of integers returned is TASK_EVENTS_INFO_COUNT.

TASK_THREAD_TIMES_INFO

The function returns information about the total time for live threads as defined by task_thread_times_info_t. The number of integers returned is TASK_THREAD_TIMES_INFO_COUNT.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task 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 task_info. In this case, task_info is filled as much as possible and task_infoCnt is set to the number of elements that would have been returned if there were enough room.

Data type: struct task_basic_info

This structure is returned in task_info by the task_info function and provides basic information about the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_BASIC_INFO flavor of task_info. It has the following members:

integer_t suspend_count

suspend count for task

integer_t base_priority

base scheduling priority

vm_size_t virtual_size

number of virtual pages

vm_size_t resident_size

number of resident pages

time_value_t user_time

total user run time for terminated threads

time_value_t system_time

total system run time for terminated threads

time_value_t creation_time

creation time stamp

Data type: task_basic_info_t

This is a pointer to a struct task_basic_info.

Data type: struct task_events_info

This structure is returned in task_info by the task_info function and provides event statistics for the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_EVENTS_INFO flavor of task_info. It has the following members:

natural_t faults

number of page faults

natural_t zero_fills

number of zero fill pages

natural_t reactivations

number of reactivated pages

natural_t pageins

number of actual pageins

natural_t cow_faults

number of copy-on-write faults

natural_t messages_sent

number of messages sent

natural_t messages_received

number of messages received

Data type: task_events_info_t

This is a pointer to a struct task_events_info.

Data type: struct task_thread_times_info

This structure is returned in task_info by the task_info function and provides event statistics for the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_THREAD_TIMES_INFO flavor of task_info. It has the following members:

time_value_t user_time

total user run time for live threads

time_value_t system_time

total system run time for live threads

Data type: task_thread_times_info_t

This is a pointer to a struct task_thread_times_info.

7.2.4 Task Execution

Function: kern_return_t task_suspend (task_t target_task)

The function task_suspend increments the task's suspend count and stops all threads in the task. As long as the suspend count is positive newly created threads will not run. This call does not return until all threads are suspended.

The count may become greater than one, with the effect that it will take more than one resume call to restart the task.

The function returns KERN_SUCCESS if the task has been suspended and KERN_INVALID_ARGUMENT if target_task is not a task.

Function: kern_return_t task_resume (task_t target_task)

The function task_resume decrements the task's suspend count. If it becomes zero, all threads with zero suspend counts in the task are resumed. The count may not become negative.

The function returns KERN_SUCCESS if the task has been resumed, KERN_FAILURE if the suspend count is already at zero and KERN_INVALID_ARGUMENT if target_task is not a task.

Function: kern_return_t task_priority (task_t task, int priority, boolean_t change_threads)

The priority of a task is used only for creation of new threads; a new thread's priority is set to the enclosing task's priority. task_priority changes this task priority. It also sets the priorities of all threads in the task to this new priority if change_threads is TRUE. Existing threads are not affected otherwise. If this priority change violates the maximum priority of some threads, as many threads as possible will be changed and an error code will be returned.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_ARGUMENT if task is not a task, or priority is not a valid priority and KERN_FAILURE if change_threads was TRUE and the attempt to change the priority of at least one existing thread failed because the new priority would have exceeded that thread's maximum priority.

Function: kern_return_t task_ras_control (task_t target_task, vm_address_t start_pc, vm_address_t end_pc, int flavor)

The function task_ras_control manipulates a task's set of restartable atomic sequences. If a sequence is installed, and any thread in the task is preempted within the range [start_pc,end_pc], then the thread is resumed at start_pc. This enables applications to build atomic sequences which, when executed to completion, will have executed atomically. Restartable atomic sequences are intended to be used on systems that do not have hardware support for low-overhead atomic primitives.

As a thread can be rolled-back, the code in the sequence should have no side effects other than a final store at end_pc. The kernel does not guarantee that the sequence is restartable. It assumes the application knows what it's doing.

A task may have a finite number of atomic sequences that is defined at compile time.

The flavor specifices the particular operation that should be applied to this restartable atomic sequence. Possible values for flavor can be:

TASK_RAS_CONTROL_PURGE_ALL

Remove all registered sequences for this task.

TASK_RAS_CONTROL_PURGE_ONE

Remove the named registered sequence for this task.

TASK_RAS_CONTROL_PURGE_ALL_AND_INSTALL_ONE

Atomically remove all registered sequences and install the named sequence.

TASK_RAS_CONTROL_INSTALL_ONE

Install this sequence.

The function returns KERN_SUCCESS if the operation has been performed, KERN_INVALID_ADDRESS if the start_pc or end_pc values are not a valid address for the requested operation (for example, it is invalid to purge a sequence that has not been registered), KERN_RESOURCE_SHORTAGE if an attempt was made to install more restartable atomic sequences for a task than can be supported by the kernel, KERN_INVALID_VALUE if a bad flavor was specified, KERN_INVALID_ARGUMENT if target_task is not a task and KERN_FAILURE if the call is not not supported on this configuration.

7.2.5 Task Special Ports

Function: kern_return_t task_get_special_port (task_t task, int which_port, mach_port_t *special_port)

The function task_get_special_port returns send rights to one of a set of special ports for the task specified by task.

The special ports associated with a task are the kernel port (TASK_KERNEL_PORT), the bootstrap port (TASK_BOOTSTRAP_PORT) and the exception port (TASK_EXCEPTION_PORT). The bootstrap port is a port to which a task may send a message requesting other system service ports. This port is not used by the kernel. The task's exception port is the port to which messages are sent by the kernel when an exception occurs and the thread causing the exception has no exception port of its own.

The following macros to call task_get_special_port for a specific port are defined in mach/task_special_ports.h: task_get_exception_port and task_get_bootstrap_port.

The function returns KERN_SUCCESS if the port was returned and KERN_INVALID_ARGUMENT if task is not a task or which_port is an invalid port selector.

Function: kern_return_t task_get_kernel_port (task_t task, mach_port_t *kernel_port)

The function task_get_kernel_port is equivalent to the function task_get_special_port with the which_port argument set to TASK_KERNEL_PORT.

Function: kern_return_t task_get_exception_port (task_t task, mach_port_t *exception_port)

The function task_get_exception_port is equivalent to the function task_get_special_port with the which_port argument set to TASK_EXCEPTION_PORT.

Function: kern_return_t task_get_bootstrap_port (task_t task, mach_port_t *bootstrap_port)

The function task_get_bootstrap_port is equivalent to the function task_get_special_port with the which_port argument set to TASK_BOOTSTRAP_PORT.

Function: kern_return_t task_set_special_port (task_t task, int which_port, mach_port_t special_port)

The function thread_set_special_port sets one of a set of special ports for the task specified by task.

The special ports associated with a task are the kernel port (TASK_KERNEL_PORT), the bootstrap port (TASK_BOOTSTRAP_PORT) and the exception port (TASK_EXCEPTION_PORT). The bootstrap port is a port to which a thread may send a message requesting other system service ports. This port is not used by the kernel. The task's exception port is the port to which messages are sent by the kernel when an exception occurs and the thread causing the exception has no exception port of its own.

The function returns KERN_SUCCESS if the port was set and KERN_INVALID_ARGUMENT if task is not a task or which_port is an invalid port selector.

Function: kern_return_t task_set_kernel_port (task_t task, mach_port_t kernel_port)

The function task_set_kernel_port is equivalent to the function task_set_special_port with the which_port argument set to TASK_KERNEL_PORT.

Function: kern_return_t task_set_exception_port (task_t task, mach_port_t exception_port)

The function task_set_exception_port is equivalent to the function task_set_special_port with the which_port argument set to TASK_EXCEPTION_PORT.

Function: kern_return_t task_set_bootstrap_port (task_t task, mach_port_t bootstrap_port)

The function task_set_bootstrap_port is equivalent to the function task_set_special_port with the which_port argument set to TASK_BOOTSTRAP_PORT.

7.2.6 Syscall Emulation

Function: kern_return_t task_get_emulation_vector (task_t task, int *vector_start, emulation_vector_t *emulation_vector, mach_msg_type_number_t *emulation_vector_count)

The function task_get_emulation_vector gets the user-level handler entry points for all emulated system calls.

Function: kern_return_t task_set_emulation_vector (task_t task, int vector_start, emulation_vector_t emulation_vector, mach_msg_type_number_t emulation_vector_count)

The function task_set_emulation_vector establishes user-level handlers for the specified system calls. Non-emulated system calls are specified with an entry of EML_ROUTINE_NULL. System call emulation handlers are inherited by the childs of task.

Function: kern_return_t task_set_emulation (task_t task, vm_address_t routine_entry_pt, int routine_number)

The function task_set_emulation establishes a user-level handler for the specified system call. System call emulation handlers are inherited by the childs of task.

7.3 Profiling

Function: kern_return_t task_enable_pc_sampling (task_t task, int *ticks, sampled_pc_flavor_t flavor)

Function: kern_return_t thread_enable_pc_sampling (thread_t thread, int *ticks, sampled_pc_flavor_t flavor)

The function task_enable_pc_sampling enables PC sampling for task, the function thread_enable_pc_sampling enables PC sampling for thread. The kernel's idea of clock granularity is returned in ticks in usecs. (this value should not be trusted). The sampling flavor is specified by flavor.

The function returns KERN_SUCCESS if the operation is completed successfully and KERN_INVALID_ARGUMENT if thread is not a valid thread.

Function: kern_return_t task_disable_pc_sampling (task_t task, int *sample_count)

Function: kern_return_t thread_disable_pc_sampling (thread_t thread, int *sample_count)

The function task_disable_pc_sampling disables PC sampling for task, the function thread_disable_pc_sampling disables PC sampling for thread. The number of sample elements in the kernel for the thread is returned in sample_count.

The function returns KERN_SUCCESS if the operation is completed successfully and KERN_INVALID_ARGUMENT if thread is not a valid thread.

Function: kern_return_t task_get_sampled_pcs (task_t task, sampled_pc_seqno_t *seqno, sampled_pc_array_t sampled_pcs, mach_msg_type_number_t *sample_count)

Function: kern_return_t thread_get_sampled_pcs (thread_t thread, sampled_pc_seqno_t *seqno, sampled_pc_array_t sampled_pcs, int *sample_count)

The function task_get_sampled_pcs extracts the PC samples for task, the function thread_get_sampled_pcs extracts the PC samples for thread. seqno is the sequence number of the sampled PCs. This is useful for determining when a collector thread has missed a sample. The sampled PCs for the thread are returned in sampled_pcs. sample_count contains the number of sample elements returned.

The function returns KERN_SUCCESS if the operation is completed successfully, KERN_INVALID_ARGUMENT if thread is not a valid thread and KERN_FAILURE if thread is not sampled.

Data type: sampled_pc_t

This structure is returned in sampled_pcs by the thread_get_sampled_pcs and task_get_sampled_pcs functions and provides pc samples for threads or tasks. It has the following members:

natural_t id

A thread-specific unique identifier.

vm_offset_t pc

A pc value.

sampled_pc_flavor_t sampletype

The type of the sample as per flavor.

Data type: sampled_pc_flavor_t

This data type specifies a pc sample flavor, either as argument passed in flavor to the thread_enable_pc_sample and thread_disable_pc_sample functions, or as member sampletype in the sample_pc_t data type. The flavor is a bitwise-or of the possible flavors defined in `mach/pc_sample.h':

SAMPLED_PC_PERIODIC

default

SAMPLED_PC_VM_ZFILL_FAULTS

zero filled fault

SAMPLED_PC_VM_REACTIVATION_FAULTS

reactivation fault

SAMPLED_PC_VM_PAGEIN_FAULTS

pagein fault

SAMPLED_PC_VM_COW_FAULTS

copy-on-write fault

SAMPLED_PC_VM_FAULTS_ANY

any fault

SAMPLED_PC_VM_FAULTS

the bitwise-or of SAMPLED_PC_VM_ZFILL_FAULTS, SAMPLED_PC_VM_REACTIVATION_FAULTS, SAMPLED_PC_VM_PAGEIN_FAULTS and SAMPLED_PC_VM_COW_FAULTS.