2.12.2  taskloop Construct

Summary The 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 
    loop-nest
  

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

 
!$omp taskloop [clause[[,] clause] ...] 
    loop-nest 
[!$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(data-sharing-attribute) 
grainsize([strict:]grain-size) 
num_tasks([strict:]num-tasks) 
collapse(n) 
final(scalar-logical-expr) 
priority(priority-value) 
untied 
mergeable 
nogroup 
allocate([allocator :] list)
       

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

Description The 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 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, the behavior is as if a task_reduction clause with the same reduction operator and list items was applied to the implicit taskgroup construct that encloses 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, 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, the number of logical 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 iterations, but less than two times the value of the grain-size expression. If the grainsize clause has the strict modifier, the number of logical iterations assigned to each generated task is equal to the value of the grain-size expression, except for the generated task that contains the sequentially last iteration, which may have fewer iterations. 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 iterations. Each task must have at least one logical iteration. The parameter of the num_tasks clause must be a positive integer expression. If the num_tasks clause has the strict modifier for a task loop with N logical iterations, the logical iterations are partitioned in a balanced manner and each partition is assigned, in order, to a generated task. The partition size is ⌈⌈N∕num-tasks⌉⌉ until the number of remaining iterations divides the number of remaining tasks evenly, at which point the partition size becomes ⌊⌊N∕num-tasks⌋⌋.

If neither a grainsize nor num_tasks clause is present, the number of loop tasks generated and the number of logical 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 the collapse clause is omitted, the behavior is as if a collapse clause with a parameter value of one was specified. The collapse clause specifies the number of loops that are collapsed into a logical iteration space that is then divided according to the grainsize and num_tasks clauses.

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.

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.

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

When a final clause is present and the final clause expression evaluates to true, the generated tasks are 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, 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).

When the untied clause is present, each generated task is an untied task.

When the mergeable clause is present, 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 region. Specifically, a taskloop-begin event for a taskloop region 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 region.

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.

Restrictions Restrictions to the taskloop construct are as follows:

• If a reduction clause is present, 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 the directive.
• At most one num_tasks clause can appear on the directive.
• Neither the grainsize clause nor the num_tasks clause may appear on the directive if any of the associated loops is a non-rectangular loop.
• 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 the 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

• Canonical loop nest form, see Section 2.11.1.
• tile construct, see Section 2.11.9.1.
• task construct, Section 2.12.1.
• if clause, see Section 2.18.
• taskgroup construct, Section 2.19.6.
• Data-sharing attribute clauses, Section 2.21.4.
• ompt_scope_begin and ompt_scope_end, see Section 4.4.4.11.
• ompt_work_taskloop, see Section 4.4.4.15.
• ompt_callback_work_t, see Section 4.5.2.5.
• ompt_callback_dispatch_t, see Section 4.5.2.6.