The Thread of Interest

The thread of interest is specified as p.t, where p is the TotalView process ID (PID) and t is the TotalView thread ID (TID). The p.t combination identifies the process and thread of interest. The thread of interest is the primary thread affected by a command. This means that it is the primary focus for a CLI command. For example, the dstep command always steps the thread of interest, but it may optionally run the rest of the threads in the process of interest and may step other processes in the group.

The CLI has two symbols with special meaning when specifying P/T sets:

• The less-than (<) character in place of the TID to indicate the lowest number worker thread in the process. If, however, the arena explicitly names a thread group, < means the lowest numbered member of the thread group. This symbol lets TotalView select the first user thread, which may not be thread 1; for example, the first and only user thread may be thread number 3 on Compaq systems.
• A dot (.) indicates the current set. While this is seldom needed interactively, it can be useful in scripts.

Process and Thread Widths

You can enter a P/T set in two ways. If you are not manipulating groups, the format is:

    [width_letter][PID][.TID]

Note:   The next section extends this format to include groups.

For example, p2.3 indicates process 2, thread 3.

While the syntax seems to indicate that you do not need to enter any element, the CLI requires that, at a minimum, you enter one of the three components. Because the CLI has an extensive set of defaults, it will try to fill in what you omit. The only requirement is that when you use more than one element, you use it in the order shown in this representation.

The width_letter indicates which processes and threads are part of this arena specifier. These letters are:

t

Thread width

A command's target is the indicated thread.

p

Process width

A command's target is the process containing the thread of interest.

g

Group width

A command's target is the group containing the process of interest.

a

All processes

A command's target is all threads in the group of interest that are in the process of interest.

d

Default width

A command's target depends on the default for each command. This is also the width to which the default focus is set. For example, the dstep command defaults to process width (run the process while stepping one thread), and the dwhere command defaults to thread width (backtrace just one thread). Default widths are listed in CLI Command Default Arena Widths.

These widths must be entered as lowercase letters.

The following figure illustrates the relationship of these specifiers:

Width Specifiers

Note:   Notice that the "g" specifier indicates control and share groups.

You can visualize this relationship as a triangle with its base on the top. This indicates that the arena focuses on a greater number of entities as you move from thread level at the bottom to "all" level at the top.

As mentioned previously, the thread of interest specifies a particular target thread, while the width specifies how many threads surrounding the thread of interest are affected. For example, the dstep command always requires a thread of interest, but entering this command can:

• Step just the thread of interest during the step operation (single-thread single-step).
• Step the thread of interest and step all threads in the process containing the thread of interest (process-level single-step).
• Step all processes in the group that have threads at the same PC (program counter) as the thread of interest (group-level single-step).

This list doesn't indicate what happens to other threads in your program when the CLI steps your thread. For more information, see Stepping.

To save a P/T set definition for later use, assign the specifiers to a Tcl variable. For example:

set myset { g2.3 t3.1 }
dfocus $myset dgo

The thread of interest can also be modified by a width specifier. As the dfocus command returns its focus set, you can save this value for later use. For example:

set save_set [dfocus] 

Examples

Here are some example specifiers:

d1.<

Use the default set for each command, focusing on the first user thread in process 1. The "<: sets the TID to the first user thread.

g2.3

Select process 2, thread 3 and set the width to "group".

t1.7

Commands act only on thread 7 of process 1.

You can leave out parts of the P/T set if what you enter is unambiguous. A missing width or PID is filled in from the current focus. A missing TID is always assumed to be <. For more information, see Incomplete Arena Specifiers.