2.9.5  loop Construct

SummaryA loop construct specifies that the iterations of the associated loops may execute concurrently and permits the encountering thread(s) to execute the loop accordingly.

Syntax

 
#pragma omp loop [clause[ [,] clause] ... ] new-line 
    for-loops
  

 
bind(binding) 
collapse(n) 
order(concurrent) 
private(list) 
lastprivate(list) 
reduction([default ,]reduction-identifier : list)
       

 
  teams 
  parallel 
  thread
       

 
!$omp loop [clause[ [,] clause] ... ] 
   do-loops 
[!$omp end loop]
  

 
bind(binding) 
collapse(n) 
order(concurrent) 
private(list) 
lastprivate(list) 
reduction([default ,]reduction-identifier : list)
       

 
  teams 
  parallel 
  thread
       

BindingIf the bind clause is present on the construct, the binding region is determined by binding. Specifically, if binding is teams and there exists an innermost enclosing teams region then the binding region is that teams region; if binding is parallel then the binding region is the innermost enclosing parallel region, which may be an implicit parallel region; and if binding is thread then the binding region is not defined. If the bind clause is not present on the construct and the loop construct is closely nested inside a teams or parallel construct, the binding region is the corresponding teams or parallel region. If none of those conditions hold, the binding region is not defined. If the binding region is a teams region, then the binding thread set is the set of master threads that are executing that region. If the binding region is a parallel region, then the binding thread set is the team of threads that are executing that region. If the binding region is not defined, then the binding thread set is the encountering thread.

DescriptionThe loop construct is associated with a loop nest that consists of one or more loops that follow the directive. The directive asserts that the iterations may execute in any order, including concurrently. The collapse clause may be used to specify how many loops are associated with the loop construct. The parameter of the collapse clause must be a constant positive integer expression. If a collapse clause is specified with a parameter value greater than 1, then the iterations of the associated loops to which the clause applies are collapsed into one larger iteration space with unspecified ordering. If no collapse clause is present or its parameter is 1, the only loop that is associated with the loop construct is the one that immediately follows the loop directive.

If more than one loop is associated with the loop construct then the number of times that any intervening code between any two associated loops will be executed is unspecified but will be at least once per iteration of the loop enclosing the intervening code and at most once per iteration of the innermost loop associated with the construct. If the iteration count of any loop that is associated with the loop construct is zero and that loop does not enclose the intervening code, the behavior is unspecified.

The iteration space of the associated loops correspond to logical iterations numbered 0,1,...,N-1 where N is the number of loop iterations, and the logical numbering denotes the sequence in which the iterations would be executed if a set of associated loop(s) were executed sequentially. At the beginning of each logical iteration, the loop iteration variable of each associated loop has the value that it would have if the set of the associated loop(s) were executed sequentially.

Each logical iteration is executed once per instance of the loop region that is encountered by the binding thread set.

If the order(concurrent) clause appears on the loop construct, the iterations of the associated loops may execute in any order, including concurrently. If the order clause is not present, the behavior is as if the order(concurrent) clause appeared on the construct.

The set of threads that may execute the iterations of the loop region is the binding thread set. Each iteration is executed by one thread from this set.

If the loop region binds to a teams region, the threads in the binding thread set may continue execution after the loop region without waiting for all iterations of the associated loop(s) to complete. The iterations are guaranteed to complete before the end of the teams region.

If the loop region does not bind to a teams region, all iterations of the associated loop(s) must complete before the encountering thread(s) continue execution after the loop region.

RestrictionsRestrictions to the loop construct are as follows:

• If the collapse clause is specified then there may be no intervening OpenMP directives between the associated loops.
• At most one collapse clause can appear on a loop directive.
• A list item may not appear in a lastprivate clause unless it is the loop iteration variable of a loop that is associated with the construct.
• If a loop construct is not nested inside another OpenMP construct and it appears in a procedure, the bind clause must be present.
• If a loop region binds to a teams or parallel region, it must be encountered by all threads in the binding thread set or by none of them.
• If the bind clause is present and binding is teams, the loop region corresponding to the loop construct must be strictly nested inside a teams region.
• If the bind clause is present and binding is parallel, the behavior is unspecified if the loop region corresponding to a loop construct is closely nested inside a simd region.
• The only constructs that may be nested inside a loop region are the loop construct, the parallel construct, the simd construct, and combined constructs for which the first construct is a parallel construct.
• A loop region corresponding to a loop construct may not contain calls to procedures that contain OpenMP directives.
• A loop region corresponding to a loop construct may not contain calls to the OpenMP Runtime API.
• If a threadprivate variable is referenced inside a loop region, the behavior is unspecified.

Cross References

• The single construct, see Section 2.8.2 on page 256.
• The Worksharing-Loop construct, see Section 2.9.2 on page 288.
• SIMD directives, see Section 2.9.3 on page 316.
• distribute construct, see Section 2.9.4.1 on page 342.