HOME
| OPENMP API Specification: Version 5.0 November 2018

2.10.2  taskloop Construct

SummaryThe taskloop construct specifies that the iterations of one or more associated loops will be executed in parallel using explicit tasks. The iterations are distributed across tasks generated by the construct and scheduled to be executed. Syntax

SVG-Viewer needed.

The syntax of the taskloop construct is as follows:  

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

where clause is one of the following:  

 
if([ taskloop :] scalar-expression) 
shared(list) 
private(list) 
firstprivate(list) 
lastprivate(list) 
reduction([default ,]reduction-identifier : list) 
in_reduction(reduction-identifier : list) 
default(shared | none) 
grainsize(grain-size) 
num_tasks(num-tasks) 
collapse(n) 
final(scalar-expr) 
priority(priority-value) 
untied 
mergeable 
nogroup 
allocate([allocator :] list)  

The taskloop directive places restrictions on the structure of all associated for-loops. Specifically, all associated for-loops must have canonical loop form (see Section 2.9.1 on page 271).

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the taskloop construct is as follows:  

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

where clause is one of the following:  

 
if([ taskloop :] scalar-logical-expression) 
shared(list) 
private(list) 
firstprivate(list) 
lastprivate(list) 
reduction([default ,]reduction-identifier : list) 
in_reduction(reduction-identifier : list) 
default(private | firstprivate | shared | none) 
grainsize(grain-size) 
num_tasks(num-tasks) 
collapse(n) 
final(scalar-logical-expr) 
priority(priority-value) 
untied 
mergeable 
nogroup 
allocate([allocator :] list)  

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

The taskloop directive places restrictions on the structure of all associated do-loops. Specifically, all associated do-loops must have canonical loop form (see Section 2.9.1 on page 271).

SVG-Viewer needed.

BindingThe binding thread set of the taskloop region is the current team. A taskloop region binds to the innermost enclosing parallel region.

DescriptionThe taskloop construct is a task generating construct. When a thread encounters a taskloop construct, the construct partitions the iterations of the associated loops into explicit tasks for parallel execution. The data environment of each generated task is created according to the data-sharing attribute clauses on the taskloop construct, per-data environment ICVs, and any defaults that apply. The order of the creation of the loop tasks is unspecified. Programs that rely on any execution order of the logical loop iterations are non-conforming. By default, the taskloop construct executes as if it was enclosed in a taskgroup construct with no statements or directives outside of the taskloop construct. Thus, the taskloop construct creates an implicit taskgroup region. If the nogroup clause is present, no implicit taskgroup region is created.

If a reduction clause is present on the taskloop construct, the behavior is as if a task_reduction clause with the same reduction operator and list items was applied to the implicit taskgroup construct enclosing the taskloop construct. The taskloop construct executes as if each generated task was defined by a task construct on which an in_reduction clause with the same reduction operator and list items is present. Thus, the generated tasks are participants of the reduction defined by the task_reduction clause that was applied to the implicit taskgroup construct.

If an in_reduction clause is present on the taskloop construct, the behavior is as if each generated task was defined by a task construct on which an in_reduction clause with the same reduction operator and list items is present. Thus, the generated tasks are participants of a reduction previously defined by a reduction scoping clause.

If a grainsize clause is present on the taskloop construct, the number of logical loop iterations assigned to each generated task is greater than or equal to the minimum of the value of the grain-size expression and the number of logical loop iterations, but less than two times the value of the grain-size expression.

The parameter of the grainsize clause must be a positive integer expression. If num_tasks is specified, the taskloop construct creates as many tasks as the minimum of the num-tasks expression and the number of logical loop iterations. Each task must have at least one logical loop iteration. The parameter of the num_tasks clause must be a positive integer expression. If neither a grainsize nor num_tasks clause is present, the number of loop tasks generated and the number of logical loop iterations assigned to these tasks is implementation defined.

The collapse clause may be used to specify how many loops are associated with the taskloop construct. The parameter of the collapse clause must be a constant positive integer expression. If no collapse clause is present or its parameter is 1, the only loop that is associated with the taskloop construct is the one that immediately follows the taskloop directive. If a collapse clause is specified with a parameter value greater than 1 and more than one loop is associated with the taskloop construct, then the iterations of all associated loops are collapsed into one larger iteration space that is then divided according to the grainsize and num_tasks clauses. The sequential execution of the iterations in all associated loops determines the order of the iterations in the collapsed iteration space.

If more than one loop is associated with the taskloop 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 taskloop construct is zero and that loop does not enclose intervening code, the behavior is unspecified.

A taskloop loop has 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 the 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.

The iteration count for each associated loop is computed before entry to the outermost loop. If execution of any associated loop changes any of the values used to compute any of the iteration counts, then the behavior is unspecified.

The integer type (or kind, for Fortran) used to compute the iteration count for the collapsed loop is implementation defined.

When an if clause is present on a taskloop construct, and if the if clause expression evaluates to false, undeferred tasks are generated. The use of a variable in an if clause expression of a taskloop construct causes an implicit reference to the variable in all enclosing constructs.

When a final clause is present on a taskloop construct and the final clause expression evaluates to true, the generated tasks will be final tasks. The use of a variable in a final clause expression of a taskloop construct causes an implicit reference to the variable in all enclosing constructs.

When a priority clause is present on a taskloop construct, the generated tasks use the priority-value as if it was specified for each individual task. If the priority clause is not specified, tasks generated by the taskloop construct have the default task priority (zero).

If the untied clause is specified, all tasks generated by the taskloop construct are untied tasks.

When the mergeable clause is present on a taskloop construct, each generated task is a mergeable task.

SVG-Viewer needed.

For firstprivate variables of class type, the number of invocations of copy constructors to perform the initialization is implementation-defined.

SVG-Viewer needed.

SVG-Viewer needed.

Note – When storage is shared by a taskloop region, the programmer must ensure, by adding proper synchronization, that the storage does not reach the end of its lifetime before the taskloop region and its descendant tasks complete their execution.

SVG-Viewer needed.

Execution Model Events The taskloop-begin event occurs after a task encounters a taskloop construct but before any other events that may trigger as a consequence of executing the taskloop. Specifically, a taskloop-begin event for a taskloop will precede the taskgroup-begin that occurs unless a nogroup clause is present. Regardless of whether an implicit taskgroup is present, a taskloop-begin will always precede any task-create events for generated tasks.

The taskloop-end event occurs after a taskloop region finishes execution but before resuming execution of the encountering task.

The taskloop-iteration-begin event occurs before an explicit task executes each iteration of a taskloop.

Tool Callbacks A thread dispatches a registered ompt_callback_work callback for each occurrence of a taskloop-begin and taskloop-end event in that thread. The callback occurs in the context of the encountering task. The callback has type signature ompt_callback_work_t. The callback receives ompt_scope_begin or ompt_scope_end as its endpoint argument, as appropriate, and ompt_work_taskloop as its wstype argument.

A thread dispatches a registered ompt_callback_dispatch callback for each occurrence of a taskloop-iteration-begin event in that thread. The callback occurs in the context of the encountering task. The callback has type signature ompt_callback_dispatch_t.

RestrictionsThe restrictions of the taskloop construct are as follows:

Cross References