HOME
| OPENMP API Specification: Version 5.1 November 2020

2.11.6  distribute Loop Constructs

2.11.6.1 distribute Construct

Summary The distribute construct specifies that the iterations of one or more loops will be executed by the initial teams in the context of their implicit tasks. The iterations are distributed across the initial threads of all initial teams that execute the teams region to which the distribute region binds.

Syntax

SVG-Viewer needed.

The syntax of the distribute construct is as follows:  

 
#pragma omp distribute [clause[ [,] clause] ... ] new-line 
   loop-nest  

where loop-nest is a canonical loop nest and clause is one of the following:  

 
private(list) 
firstprivate(list) 
lastprivate(list) 
collapse(n) 
dist_schedule(kind[, chunk_size]) 
allocate([allocator :]list) 
order([ order-modifier :]concurrent)  

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the distribute construct is as follows:  

 
!$omp distribute [clause[ [,] clause] ... ] 
   loop-nest 
[!$omp end distribute]  

where loop-nest is a canonical loop nest and clause is one of the following:  

 
private(list) 
firstprivate(list) 
lastprivate(list) 
collapse(n) 
dist_schedule(kind[, chunk_size]) 
allocate([allocator :]list) 
order([ order-modifier :]concurrent)  

If an end distribute directive is not specified, an end distribute directive is assumed at the end of the do-loops.

SVG-Viewer needed.

Binding The binding thread set for a distribute region is the set of initial threads executing an enclosing teams region. A distribute region binds to this teams region.

Description The distribute construct is associated with a loop nest consisting of one or more loops that follow the directive.

The collapse clause may be used to specify how many loops are associated with the distribute construct. The parameter of the collapse clause must be a constant positive integer expression. If the collapse clause is omitted, the behavior is as if a collapse clause with a parameter value of one was specified.

No implicit barrier occurs at the end of a distribute region. To avoid data races the original list items that are modified due to lastprivate or linear clauses should not be accessed between the end of the distribute construct and the end of the teams region to which the distribute binds.

At the beginning of each logical iteration, the loop iteration variable or the variable declared by range-decl of each associated loop has the value that it would have if the set of the associated loops was executed sequentially.

If the dist_schedule clause is specified, kind must be static. If specified, iterations are divided into chunks of size chunk_size. These chunks are assigned to the initial teams of the league in a round-robin fashion in the order of the initial team number. When chunk_size is not specified, the iteration space is divided into chunks that are approximately equal in size, and at most one chunk is distributed to each initial team of the league.

When dist_schedule clause is not specified, the schedule is implementation defined.

If an order clause is present then the semantics are as described in Section 2.11.3.

The schedule is reproducible if one of the following conditions is true:

Programs can only depend on which team executes a particular iteration if the schedule is reproducible. Schedule reproducibility is also used for determining its consistency with other schedules (see Section 2.11.2).

Execution Model Events The distribute-begin event occurs after an implicit task encounters a distribute construct but before the task starts to execute the structured block of the distribute region.

The distribute-end event occurs after an implicit task finishes execution of a distribute region but before it resumes execution of the enclosing context.

Tool Callbacks A thread dispatches a registered ompt_callback_work callback with ompt_scope_begin as its endpoint argument and ompt_work_distribute as its wstype argument for each occurrence of a distribute-begin event in that thread. Similarly, a thread dispatches a registered ompt_callback_work callback with ompt_scope_end as its endpoint argument and ompt_work_distribute as its wstype argument for each occurrence of a distribute-end event in that thread. The callbacks occur in the context of the implicit task. The callbacks have type signature ompt_callback_work_t.

Restrictions Restrictions to the distribute construct are as follows:

Cross References

2.11.6.2 distribute simd Construct

Summary The distribute simd construct specifies a loop that will be distributed across the primary threads of the teams region and executed concurrently using SIMD instructions. The distribute simd construct is a composite construct.

Syntax

SVG-Viewer needed.

The syntax of the distribute simd construct is as follows:  

 
#pragma omp distribute simd [clause[ [,] clause] ... ] new-line 
   loop-nest  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or simd directives with identical meanings and restrictions.

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the distribute simd construct is as follows:  

 
!$omp distribute simd [clause[ [,] clause] ... ] 
   loop-nest 
[!$omp end distribute simd]  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or simd directives with identical meanings and restrictions.

If an end distribute simd directive is not specified, an end distribute simd directive is assumed at the end of the do-loops.

SVG-Viewer needed.

Description The distribute simd construct will first distribute the logical iterations of the associated loops across the initial tasks of the teams region in a manner consistent with any clauses that apply to the distribute construct. Each resulting chunk of iterations will then be converted to a SIMD loop in a manner consistent with any clauses that apply to the simd construct.

Execution Model Events This composite construct generates the same events as the distribute construct.

Tool Callbacks This composite construct dispatches the same callbacks as the distribute construct.

Restrictions All restrictions to the distribute and simd constructs apply to the distribute simd construct. In addition, the following restrictions apply:

Cross References

2.11.6.3 Distribute Parallel Worksharing-Loop Construct

Summary The distribute parallel worksharing-loop construct specifies a loop that can be executed in parallel by multiple threads that are members of multiple teams. The distribute parallel worksharing-loop construct is a composite construct.

Syntax

SVG-Viewer needed.

The syntax of the distribute parallel worksharing-loop construct is as follows:  

 
#pragma omp distribute parallel for [clause[ [,] clause] ... ] new-line 
    loop-nest  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or parallel worksharing-loop directives with identical meanings and restrictions.

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the distribute parallel worksharing-loop construct is as follows:  

 
!$omp distribute parallel do [clause[ [,] clause] ... ] 
    loop-nest 
[!$omp end distribute parallel do]  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or parallel worksharing-loop directives with identical meanings and restrictions.

If an end distribute parallel do directive is not specified, an end distribute parallel do directive is assumed at the end of the do-loops.

SVG-Viewer needed.

Description The distribute parallel worksharing-loop construct will first distribute the logical iterations of the associated loops across the initial tasks of the teams region in a manner consistent with any clauses that apply to the distribute construct. Each resulting chunk of iterations will then execute as if part of a parallel worksharing-loop region in a manner consistent with any clauses that apply to the parallel worksharing-loop construct.

Execution Model Events This composite construct generates the same events as the distribute and parallel worksharing-loop constructs.

Tool Callbacks This composite construct dispatches the same callbacks as the distribute and parallel worksharing-loop constructs.

Restrictions All restrictions to the distribute and parallel worksharing-loop constructs apply to the distribute parallel worksharing-loop construct. In addition, the following restrictions apply:

Cross References

2.11.6.4 Distribute Parallel Worksharing-Loop SIMD Construct

Summary The distribute parallel worksharing-loop SIMD construct specifies a loop that can be executed concurrently using SIMD instructions in parallel by multiple threads that are members of multiple teams. The distribute parallel worksharing-loop SIMD construct is a composite construct.

Syntax

SVG-Viewer needed.

The syntax of the distribute parallel worksharing-loop SIMD construct is as follows:  

 
#pragma omp distribute parallel for simd \ 
            [clause[ [,] clause] ... ] new-line 
    loop-nest  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or parallel worksharing-loop SIMD directives with identical meanings and restrictions.

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the distribute parallel worksharing-loop SIMD construct is as follows:  

 
!$omp distribute parallel do simd [clause[ [,] clause] ... ] 
    loop-nest 
[!$omp end distribute parallel do simd]  

where loop-nest is a canonical loop nest and clause can be any of the clauses accepted by the distribute or parallel worksharing-loop SIMD directives with identical meanings and restrictions.

If an end distribute parallel do simd directive is not specified, an end distribute paralleldo simd directive is assumed at the end of the do-loops.

SVG-Viewer needed.

Description The distribute parallel worksharing-loop SIMD construct will first distribute the logical iterations of the associated loops across the initial tasks of the teams region in a manner consistent with any clauses that apply to the distribute construct. Each resulting chunk of iterations will then execute as if part of a parallel worksharing-loop SIMD region in a manner consistent with any clauses that apply to the parallel worksharing-loop SIMD construct.

Execution Model Events This composite construct generates the same events as the distribute and parallel worksharing-loop SIMD constructs.

Tool Callbacks This composite construct dispatches the same callbacks as the distribute and parallel worksharing-loop SIMD constructs.

Restrictions All restrictions to the distribute and parallel worksharing-loop SIMD constructs apply to the distribute parallel worksharing-loop SIMD construct. In addition, the following restrictions apply:

Cross References