dbarrier

Defines a process or thread barrier breakpoint

Format:

Creates a barrier breakpoint at a source location

dbarrier source-loc [ -stop_when_hit width ]
    [ -stop_when_done width ]

Creates a barrier breakpoint at an address

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

Arguments:

source-loc

The breakpoint location as a line number or as a string containing a file name, function name, and line number, each separated by # characters; for example, #file#line. If you omit parts of this specification, the CLI will create them for you. For more information, see Qualifying Symbol Names.

-address addr

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

-stop_when_hit width

Tells the CLI what else it should stop when it stops the thread arriving at a barrier.

If you do not use this option, the value of the BARRIER_STOP_ALL state variable indicates what TotalView will stop.

This command's width argument indicates what else TotalView stops. You can enter one of the following three values:

group

Stops all processes in the control group when the barrier is hit.

process

Stops the process that hit the barrier.

none

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

-stop_when_done width

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

If you do not use this option, the value of the BARRIER_STOP_WHEN_DONE state variable indicates what else TotalView stops.

The width argument indicates what else is stopped. You can enter one of the following three values:

group

Stops the entire control group when the barrier is satisfied.

process

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

You will find information on the "satisfaction set" in this topic's Description section.

none

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

Description:

The dbarrier command sets a process or thread barrier breakpoint that is triggered 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 are affected by the barrier. 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 reaching 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. They are just released; they are not continued. That is, TotalView leaves them stopped at the barrier. If you now continue the process, those threads stopped at the barrier also run along with any other threads that were not participating with the barrier. After they 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 may also stop the thread's process or control group. Neither are held.

TotalView determines what processes and threads 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.

Note:   Barriers can create deadlocks. For example, if two threads participate in two different barriers, each could be left waiting at different barriers, barriers that can never be satisfied. A deadlock can also occur if a barrier is set in a procedure that will never be 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 tells TotalView what other threads it should stop when a thread arrives at a barrier.

The -stop_when_done option controls the set of additional threads that TotalView will stop 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 will 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 state variables.

The none argument for these options indicate that the CLI should not stop additional threads.

• If -stop_when_hit is none when a thread hits a thread barrier, TotalView just stops that thread; it does not stop other threads.
   
• If -stop_when_done to none, TotalView does not stop additional threads, aside from the ones that are already stopped at the barrier.

TotalView plants the barrier point in the processes or groups specified in the current focus. If the current focus:

• Does not indicate an explicit group, the CLI creates a process barrier across the share group.
   
• Indicates a process group, the CLI creates a process barrier that is satisfied when all members of that group reach the barrier.
   
• 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 (which is 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 
2
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, stop_when_hit remains set to thread:

1.<> baw 580 -stop_when_hit thread 
1
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:

You may find the following aliases useful:

Alias	Definition	Meaning
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. TotalView sets the set of threads stopped when the barrier is satisfied to the process containing 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 will be the entire control group.

Examples:

dbarrier 123

Stops each process in the control group when it A arrives at line 123, it is stopped. After all 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 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 on 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.