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.