dbarrier

Totalview® Reference Guide : Part I: CLI Commands : CLI Commands : dbarrier

dbarrier

Defines a process or thread barrier breakpoint

Format:

Creates a barrier breakpoint at a source location

dbarrier breakpoint-expr [ -stop_when_hit width ]
[ -stop_when_done width ] [ -pending ]

Creates a barrier breakpoint at an address

dbarrier -address addr [ -stop_when_hit width ]
[ -stop_when_done width ] [ -pending ]

Arguments:

breakpoint-expr

This argument can be entered in more than one way, usually using a line number or a pathname containing a file name, function name, and line number, each separated by # characters (for example, file#line). For more information, see “Qualifying Symbol Names” in Chapter 13 of the TotalView User Guide.

For more information on breakpoint expressions, see dbreak, particularly Breakpoint Expressions.

-address addr

The barrier breakpoint location as an absolute address in the address space of the program.

-stop_when_hit width

Identifies, using the width argument, any additional processes or threads to stop when stopping the thread that arrives at a barrier point.

If you do not use this option, the value of BARRIER_STOP_ALL indicates what to stop.

The argument width may have one of the following three values:

group

Stops all processes in the control group when the execution reaches the barrier point.

process

Stops the process that hit the barrier.

none

Stops only the thread that hit the barrier; that is, the thread is held and all other threads continue running. If you apply this width to a process barrier breakpoint, TotalView stops the process that hit the breakpoint.

-stop_when_done width

After all processes or threads reach the barrier, releases all processes and threads held at the barrier. (Released means that these threads and processes can run.) Setting this option stops additional threads contained in the same group or process.

If you do not use this option, the value of BARRIER_STOP_WHEN_DONE indicates any other processes or threads to stop.

Use the width argument indicates other stopped processes or threads. You can enter one of the following three values:

group

Stops the entire control group when the barrier is satisfied.

process

Stops the processes that contain threads in the satisfaction set when the barrier is satisfied.

none

Stops the satisfaction set. For process barriers, process and none have the same effect. This is the default if the BARRIER_STOP_WHEN_DONE variable is none.

-pending

If TotalView cannot find a location to set the barrier, adding this option creates the barrier anyway. As shared libraries are read, TotalView checks to see if it can be set in the newly loaded library. For more information on this option, see dbreak.

Description:

The dbarrier command sets a process or thread barrier breakpoint that triggers when execution arrives at a location. This command returns the ID of the newly created breakpoint.

The dbarrier command is most often used to synchronize a set of threads. The P/T set defines which threads the barrier affects. When a thread reaches a barrier, it stops, just as it does for a breakpoint. The difference is that TotalView prevents—that is, holds—each thread that reaches the barrier from responding to resume commands (for example, dstep, dnext, and dgo) until all threads in the affected set arrive at the barrier. When all threads reach the barrier, TotalView considers the barrier to be satisfied and releases these threads. Note that they are just released, not continued. That is, TotalView leaves them stopped at the barrier. If you continue the process, those threads stopped at the barrier also run along with any other threads that were not participating with the barrier. After the threads are released, they can respond to resume commands.

If the process is stopped and then continued, the held threads, including the ones waiting on an unsatisifed barrier, do not run. Only unheld threads run.

The satisfaction set for the barrier is determined by the current focus. If the focus group is a thread group, TotalView creates a thread barrier:

When a thread hits a process barrier, TotalView holds the thread’s process.

When a thread hits a thread barrier, TotalView holds the thread; TotalView might also stop the thread’s process or control group. While they are stopped, neither is held.

TotalView determines the default focus width based on the setting of the SHARE_ACTION_POINT variable. If it is set to true, the default is group. Otherwise, it is process.

TotalView determines the processes and threads that are part of the satisfaction set by taking the intersection of the share group with the focus set. (Barriers cannot extend beyond a share group.)

The CLI displays an error message if you use an inconsistent focus list.

Barriers can create deadlocks. For example, if two threads participate in two different barriers, each could be left waiting at different barriers that can never be satisfied. A deadlock can also occur if a barrier is set in a procedure that is never invoked by a thread in the affected set. If a deadlock occurs, use the ddelete command to remove the barrier, since deleting the barrier also releases any threads held at the barrier.

The -stop_when_hit option specifies if other threads should stop when a thread arrives at a barrier.

The -stop_when_done option controls the set of additional threads that are stopped when the barrier is finally satisfied. That is, you can also stop an additional collection of threads after the last expected thread arrives, and all the threads held at the barrier are released. Normally, you want to stop the threads contained in the control group.

If you omit a stop option, TotalView sets the default behavior by using the BARRIER_STOP_ALL and BARRIER_STOP_WHEN_DONE variables.

Use the none argument for these options to not stop additional threads.

If -stop_when_hit is none when a thread hits a thread barrier, TotalView stops only that thread; it does not stop other threads.

If -stop_when_done is none, TotalView does not stop additional threads, aside from the ones that are already stopped at the barrier.

TotalView places the barrier point in the processes or groups specified in the current focus, as follows:

If the current focus does not indicate an explicit group, the CLI creates a process barrier across the share group.

If the current focus indicates a process group, the CLI creates a process barrier that is satisfied when all members of that group reach the barrier.

If the current focus indicates a thread group, TotalView creates a thread barrier that is satisfied when all members of the group arrive at the barrier.

The following example illustrates these differences. If you set a barrier with the focus set to a control group (the default), TotalView creates a process barrier. This means that the -stop_when_hit value is set to process even though you specified thread.

d1.<> dbarrier 580 -stop_when_hit thread

d1.<> ac 2

1 shared action point for group 3:

2 addr=0x120005598 [../regress/fork_loop.cxx#580] Enabled (barrier)

Share in group: true

Stop when hit: process

Stop when done: process

process barrier; satisfaction set = group 1

However, if you create the barrier with a specific workers focus, the stop when hit property remains set to thread:

1.<> baw 580 -stop_when_hit thread

d1.<> ac 1

1 unshared action point for process 1:

1 addr=0x120005598 [../regress/fork_loop.cxx#580]

Enabled (barrier)

Share in group: false

Stop when hit: thread

Stop when done: process

thread barrier; satisfaction set = group 2

Command alias:


Alias	Definition	Description
ba	dbarrier	Defines a barrier.
baw	{dfocus pW dbarrier -stop_when_done process}	Creates a thread barrier across the worker threads in the process of interest (POI). TotalView sets the set of threads stopped when the barrier is satisfied to the process that contains the satisfaction set.
BAW	{dfocus gW dbarrier -stop_when_done group}	Creates a thread barrier across the worker threads in the share group of interest. The set of threads stopped when the barrier is satisfied is the entire control group.

Examples:

dbarrier 123

Stops each process in the control group when it arrives at line 123. After all processes arrive, the barrier is satisfied, and TotalView releases all processes.

dfocus {p1 p2 p3} dbarrier my_proc

Holds each thread in processes 1, 2, and 3 as it arrives at the first executable line in procedure my_proc. After all threads arrive, the barrier is satisfied and TotalView releases all processes.

dfocus gW dbarrier 642 -stop_when_hit none

Sets a thread barrier at line 642 in the workers group. The process is continued automatically as each thread arrives at the barrier. That is, threads that are not at this line continue running.