Next: , Previous: Thread Termination, Up: Thread Interface


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.