Chapter 9 Thread Objects Window

This help file contains information for the Thread Objects Window, which applies only to the IBM AIX platform.

After you select the Tools > Thread Object command, TotalView displays a window containing the following four pages:

You must set up to six variables when debugging threaded applications. Here’s what you would do in the C shell:

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.

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:

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.

The mutex type. These types are set using the pthread_mutexattr_settype() call on the attribute object before the mutex is initialized.

The mutex is locked. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.

The mutex can only be manipulated by threads in the process that initialized the mutex.

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

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.

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.

The Condition Variable Page lists all the condition variables known in this process.

For each condition variable, TotalView displays the following information:

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.

This value indicates if the condition variable can be shared by other processes.

The condition variable can only be manipulated by the process that initialized it.

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

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.

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

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.

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:

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:

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.

Locked for reading. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.

Locked for writing. By default, this is shown in blue; its color is the same as the thread’s stopped state flag color.

This value indicates if the read-write lock can be shared by other processes.

The read-write lock can only be manipulated by the process that initialized it.

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

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.

The memory address of the read-write lock. You can open a window displaying the read-write lock data by diving on this field.

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.

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.

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.

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.