TotalView Online Help : Chapter 8 Thread Objects Window
Chapter 8 Thread Objects Window
This help file contains information for the Thread Objects Window, which applies only to the IBM AIX platform.
IBM AIX
After you select the Tools > Thread Object command, TotalView displays a window containing the following four pages:
Mutexes Page
Condition Variables Page
R/W Locks Page
Data Keys Page
You must set up to six variables when debugging threaded applications. Here’s what you would do in the C shell:
setenv AIXTHREAD_MNRATIO "1:1"
setenv AIXTHREAD_SLPRATIO "1:1"
setenv AIXTHREAD_SCOPE "S"
setenv AIXTHREAD_COND_DEBUG "ON"
setenv AIXTHREAD_MUTEX_DEBUG "ON"
setenv AIXTHREAD_RWLOCK_DEBUG "ON"
The first three variables must be set. Depending upon what you need to examine, you will also need to set one or more of the “DEBUG” variables.
Do not, however, set the AIXTHREAD_DEBUG variable. If you have set it, you should unset it before running TotalView
 
NOTE >> Setting these variables can slow down your application’s performance. None of them should be set when you are running non-debugging versions of your program.
Mutexes Page
A mutex is a mutual exclusion object that allows multiple threads to synchronize access to shared resources. A mutex has two states: locked and unlocked. Once a mutex is locked by a thread, other threads attempting to lock it will block. Only after a locking thread unlocks (releases) the mutex can one of the blocked threads acquire (lock) the mutex and proceed.
This page contains a list of all mutexes known in a process.
For each mutex, TotalView displays the following information:
ID
The sequence number assigned to a mutex by the threads package. Diving into this field opens a Variable Window containing a view of the mutex’s data.
Type
The mutex type. These types are set using the pthread_mutexattr_settype() call on the attribute object before the mutex is initialized.
The type is one of the following:
Normal
A normal mutex.
Recurs
A recursive mutex.
ErrChk
An error-check mutex.
NRecNP
A non-portable, non-recursive mutex.
RcurNP
A non-portable, recursive mutex.
FastNP
A non-portable, fast mutex.
State
The mutex lock state is displayed as follows:
Unlocked
The mutex is unlocked.
Locked
The mutex is locked. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.
Pshared
This value indicates if the mutex can be shared by other processes.
Private
The mutex can only be manipulated by threads in the process that initialized the mutex.
Shared
The mutex can be manipulated by any process that has access to the mutex’s memory. (Some versions of IBM’s system libraries cannot provide information on shared mutexes. If this information is not available, TotalView only describes private mutexes.)
Owner
If the mutex is locked, this field displays the locking thread’s system TID.
Diving on this number tells TotalView to display the locking thread’s Process Window. This is the same window that TotalView would display if you dive or select the thread's entry in the Root Window’s Attached Page.
If threads are waiting for this mutex, their system TIDs are shown beneath the owner field, with one thread ID displayed on each line. You can open a Process Window for these waiting threads by diving or selecting on its number.
 
If TotalView cannot obtain this information, it does not show waiting thread system TIDs.
Address
This field contains the memory address of the mutex. You can open a Variable Window containing a view of the mutex’s data by diving on this field.
Condition Variables Page
The Condition Variable Page lists all the condition variables known in this process.
For each condition variable, TotalView displays the following information:
ID
The ID is the sequence number assigned to this condition variable by the threads package. Diving into this field opens a Variable Window containing a view of the condition variable’s data.
Pshared
This value indicates if the condition variable can be shared by other processes.
Private
The condition variable can only be manipulated by the process that initialized it.
Shared
The condition variable can be manipulated by any process that has access to its memory. (Some versions of IBM’s system libraries cannot provide information on shared condition values to TotalView. If this information is not available, TotalView only describes private condition values.)
Waiters
If threads are waiting for this condition variable, TotalView displays their system TIDs, one thread for each line, on the lines following the condition variable. Diving or selecting entries in the list of waiting threads opens windows for them.
 
If TotalView cannot obtain this information, it does not show waiting threads.
Mutex
This field contains the ID of the mutex that guards the condition variable. If TotalView can translate the ID into an address, diving into this field opens a Variable Window containing a view of the guard mutex’s data.
TotalView can only translate this ID if it has already been initialized. That can be done statically or by using an attributes object. See the following mutex and condition variable man pages for more information: pthread_cond_init (3), pthread_mutex_init (3), pthread_cond_initializer (3), and pthread_mutex_initializer (3).
Address
This field has the condition variable’s memory address. Diving into the address field opens a Variable Window containing a view of the actual condition variable’s data.
R/W Locks Page
A read-write lock is a mutual exclusion object that allows multiple threads to synchronize access to shared resources. A read-write lock has three states:
Free
Read-locked
Write-locked
A free lock can be locked by any number of readers or by one writer. Once a read-write lock is locked by a thread for one kind of access, other threads attempting to lock it for other kinds of access will block. When locking threads unlock (release) the read-write lock, blocked threads can acquire (lock) it and proceed.
This page lists all read-write locks known in this process.
For each lock, TotalView displays the following information:
ID
This field contains the sequence number assigned to this read-write lock by the threads package. Diving into this field opens a window containing the read-write lock data.
State
This field displays the read-write lock state as follows:
Free
Unlocked.
Read
Locked for reading. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.
Write
Locked for writing. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.
Pshared
This value indicates if the read-write lock can be shared by other processes.
Private
The read-write lock can only be manipulated by the process that initialized it.
Shared
The read-write lock can be manipulated by any process that has access to its memory. (Some versions of IBM's system libraries cannot provide information on shared read-write locks to TotalView. If this information is not available, TotalView only describes private read-write locks.)
Owner
If the read-write lock is locked, this field displays the system TID of a locking thread. Diving or selecting on this number tells TotalView to display the Process Window for that thread. TotalView displays the same window if you dive or select the thread's entry in the Root Window’s Attached Page.
If threads are waiting for this read-write lock, their system TIDs are shown beneath the system TID in this field, with one thread ID being displayed for each line in the window. That is, threads that are waiting to read and threads waiting to write are grouped together.
You can open a Process Window for a waiting thread by diving or selecting its number.
If you cannot obtain this information, it does not show blocked thread lines.
 
NOTE >> Some versions of IBM’s system libraries cannot provide the correct owner TID for read-write locks locked for reading. In these cases, the owner TID can only be trusted when the lock is in its write state.
Address
The memory address of the read-write lock. You can open a window displaying the read-write lock data by diving on this field.
Data Keys Page
A pthread-specific data key is an object that can have a pointer value of type void * associated with it for each pthread in a process.
This window contains a list of all keys known in this process.
TotalView displays information for each key. Many applications initially set keys to zero (the NULL pointer value) using pthread_set_specific(). Note that a key’s information is not displayed until a thread sets a value for it, even if the value set is NULL.
ID
This field contains the sequence number assigned to this key by the threads package. Only the line for the first thread’s value for a key will contain an ID; subsequent lines for the same key omit the ID as a way of visually grouping values with the same ID.
Thread
This field has the system TIDs of the threads that have a value for this key. Diving or selecting on this number tells TotalView to display the Process Window for the thread. TotalView displays the same window if you dive or select the thread’s entry in the Root Window’s Attached Page.
Value
This field contains the contents of the key for a pthread. Diving into this field opens a window containing a view of the actual key data.