Defining the Thread of Interest (TOI)
The TOI 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 POI (Process of Interest) and TOI. The TOI is the primary thread affected by a command. This means that it is the primary focus for a TotalView command. For example, while the dstep command always steps the TOI, it may also run the rest of the threads in the POI and step other processes in the group.
In addition to using numerical values, you can also use two special symbols:
• The less-than character (<) indicates the lowest numbered worker thread in a process, and is used instead of the TID value. If, however, the arena explicitly names a thread group, the < symbol means the lowest numbered member of the thread group. This symbol lets TotalView select the first user thread, which is not necessarily thread 1.
• A dot (.) indicates the current set. Although you seldom use this symbol interactively, it can be useful in scripts.
About Process and Thread Widths
You can enter a P/T set in two ways. If you’re not manipulating groups, the format is as follows:
[width_letter][pid][.tid]
NOTE >> "Specifying Groups in P/T Sets" extends this format to include groups. When using P/T sets, you can create sets with just width indicators or just group indicators, or both.
For example, p2.3 indicates process 2, thread 3.
Although the syntax seems to indicate that you do not need to enter any element, TotalView requires that you enter at least one. Because TotalView tries to determine what it can do based on what you type, it tries to fill in what you omit. The only requirement is that when you use more than one element, you use them in the order shown here.
You can leave out parts of the P/T set if what you do 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
"Naming Incomplete Arenas".
The width_letter indicates which processes and threads are part of the arena. You can use the following letters:
t
Thread width
A command’s target is the indicated thread.
p
Process width
A command’s target is the process that contains the TOI.
g
Group width
A command’s target is the group that contains the POI. This indicates control and share groups.
a
All processes
A command’s target is all threads in the GOI that are in the POI.
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.
You must use lowercase letters to enter these widths.
Figure 255The following figure illustrates how these specifiers relate to one another.
The g specifier indicates control and share groups. This inverted triangle 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 TOI specifies a target thread, while the width specifies how many threads surrounding the TOI are also affected. For example, the dstep command always requires a TOI, but entering this command can do the following:
• Step just the TOI during the step operation (thread-level single-step).
• Step the TOI and step all threads in the process that contain the TOI (process-level single-step).
• Step all processes in the group that have threads at the same PC as the TOI (group-level single-step).
This list doesn’t indicate what happens to other threads in your program when TotalView steps your thread. For more information, see
"Stepping (Part II): Examples".
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
As the dfocus command returns its focus set, you can save this value for later use; for example:
set save_set [dfocus]
Specifier Examples
The following are some sample specifiers:
g2.3
Select process 2, thread 3, and set the width to group.
t1.7
Commands act only on thread 7 or process 1.
d1.<
Use the default set for each command, focusing on the first user thread in process 1. The less-than symbol (<) sets the TID to the first user thread.
