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

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

 
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)
       

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

 
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)
       

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.

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.

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:

• A program that branches into or out of a taskloop region is non-conforming.
• No OpenMP directive may appear in the region between any associated loops.
• If a collapse clause is specified, exactly one loop must occur in the region at each nesting level up to the number of loops specified by the parameter of the collapse clause.
• If a reduction clause is present on the taskloop directive, the nogroup clause must not be specified.
• The same list item cannot appear in both a reduction and an in_reduction clause.
• At most one grainsize clause can appear on a taskloop directive.
• At most one num_tasks clause can appear on a taskloop directive.
• The grainsize clause and num_tasks clause are mutually exclusive and may not appear on the same taskloop directive.
• At most one collapse clause can appear on a taskloop directive.
• At most one if clause can appear on the directive.
• At most one final clause can appear on the directive.
• At most one priority clause can appear on the directive.

Cross References

• task construct, Section 2.10.1 on page 384.
• if clause, see Section 2.15 on page 619.
• taskgroup construct, Section 2.17.6 on page 648.
• Data-sharing attribute clauses, Section 2.19.4 on page 842.
• default clause, see Section 2.19.4.1 on page 843.
• ompt_scope_begin and ompt_scope_end, see Section 4.4.4.11 on page 1289.
• ompt_work_taskloop, see Section 4.4.4.15 on page 1292.
• ompt_callback_work_t, see Section 4.5.2.5 on page 1329.
• ompt_callback_dispatch_t, see Section 4.5.2.6 on page 1332.