HOME
| OPENMP API Specification: Version 5.0 November 2018

2.17.8  flush Construct

SummaryThe flush construct executes the OpenMP flush operation. This operation makes a thread’s temporary view of memory consistent with memory and enforces an order on the memory operations of the variables explicitly specified or implied. See the memory model description in Section 1.4 on page 55 for more details. The flush construct is a stand-alone directive.

Syntax

SVG-Viewer needed.

The syntax of the flush construct is as follows:  

 
#pragma omp flush [memory-order-clause] [(list)] new-line  

where memory-order-clause is one of the following:  

 
acq_rel 
release 
acquire  

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the flush construct is as follows:  

 
!$omp flush [memory-order-clause] [(list)]  

where memory-order-clause is one of the following:  

 
acq_rel 
release 
acquire  

SVG-Viewer needed.

BindingThe binding thread set for a flush region is the encountering thread. Execution of a flush region affects the memory and the temporary view of memory of only the thread that executes the region. It does not affect the temporary view of other threads. Other threads must themselves execute a flush operation in order to be guaranteed to observe the effects of the flush operation of the encountering thread.

DescriptionIf memory-order-clause is not specified then the flush construct results in a strong flush operation with the following behavior. A flush construct without a list, executed on a given thread, operates as if the whole thread-visible data state of the program, as defined by the base language, is flushed. A flush construct with a list applies the flush operation to the items in the list, and the flush operation does not complete until the operation is complete for all specified list items. An implementation may implement a flush with a list by ignoring the list, and treating it the same as a flush without a list.

If no list items are specified, the flush operation has the release and/or acquire flush properties:

SVG-Viewer needed.

If a pointer is present in the list, the pointer itself is flushed, not the memory block to which the pointer refers.

SVG-Viewer needed.

SVG-Viewer needed.

If the list item or a subobject of the list item has the POINTER attribute, the allocation or association status of the POINTER item is flushed, but the pointer target is not. If the list item is a Cray pointer, the pointer is flushed, but the object to which it points is not. If the list item is of type C_PTR, the variable is flushed, but the storage that corresponds to that address is not flushed. If the list item or the subobject of the list item has the ALLOCATABLE attribute and has an allocation status of allocated, the allocated variable is flushed; otherwise the allocation status is flushed.

SVG-Viewer needed.

SVG-Viewer needed.

Note – Use of a flush construct with a list is extremely error prone and users are strongly discouraged from attempting it. The following examples illustrate the ordering properties of the flush operation. In the following incorrect pseudocode example, the programmer intends to prevent simultaneous execution of the protected section by the two threads, but the program does not work properly because it does not enforce the proper ordering of the operations on variables a and b. Any shared data accessed in the protected section is not guaranteed to be current or consistent during or after the protected section. The atomic notation in the pseudocode in the following two examples indicates that the accesses to a and b are atomic write and atomic read operations. Otherwise both examples would contain data races and automatically result in unspecified behavior. The flush operations are strong flushes that are applied to the specified flush lists

Incorrect example:       a = b = 0

    thread 1

    thread 2

  

atomic(b = 1)

atomic(a = 1)

flush(b)

flush(a)

flush(a)

flush(b)

atomic(tmp = a)

atomic(tmp = b)

if (tmp == 0) then

if (tmp == 0) then

  protected section

  protected section

end if

end if

The problem with this example is that operations on variables a and b are not ordered with respect to each other. For instance, nothing prevents the compiler from moving the flush of b on thread 1 or the flush of a on thread 2 to a position completely after the protected section (assuming that the protected section on thread 1 does not reference b and the protected section on thread 2 does not reference a). If either re-ordering happens, both threads can simultaneously execute the protected section.

The following pseudocode example correctly ensures that the protected section is executed by not more than one of the two threads at any one time. Execution of the protected section by neither thread is considered correct in this example. This occurs if both flushes complete prior to either thread executing its if statement.

Correct example:       a = b = 0

    thread 1

    thread 2

  

atomic(b = 1)

atomic(a = 1)

flush(a,b)

flush(a,b)

atomic(tmp = a)

atomic(tmp = b)

if (tmp == 0) then

if (tmp == 0) then

  protected section

  protected section

end if

end if

The compiler is prohibited from moving the flush at all for either thread, ensuring that the respective assignment is complete and the data is flushed before the if statement is executed.

SVG-Viewer needed.

Execution Model Events The flush event occurs in a thread that encounters the flush construct.

Tool Callbacks A thread dispatches a registered ompt_callback_flush callback for each occurrence of a flush event in that thread. This callback has the type signature ompt_callback_flush_t.

RestrictionsThe following restrictions apply to the flush construct:

Cross References

2.17.8.1 Implicit Flushes

Flush operations implied when executing an atomic region are described in Section 2.17.7.

A flush region that corresponds to a flush directive with the release clause present is implied at the following locations:

A flush region that corresponds to a flush directive with the acquire clause present is implied at the following locations:

SVG-Viewer needed.

Note – A flush region is not implied at the following locations:

SVG-Viewer needed.

The synchronization behavior of implicit flushes is as follows: