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

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 values 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, Scheduling Policy.

integer_t data

Policy-dependent scheduling information, 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.