task Construct

| OPENMP API Specification: Version 5.1 November 2020

2.12.1 task Construct

Summary The task construct defines an explicit task.

Syntax

The syntax of the task construct is as follows:

 
#pragma omp task [clause[ [,] clause] ... ] new-line 
    structured-block

where clause is one of the following:

 
if([ task :] scalar-expression) 
final(scalar-expression) 
untied 
default(data-sharing-attribute) 
mergeable 
private(list) 
firstprivate(list) 
shared(list) 
in_reduction(reduction-identifier : list) 
depend([depend-modifier,] dependence-type : locator-list) 
priority(priority-value) 
allocate([allocator :] list) 
affinity([aff-modifier :] locator-list) 
detach(event-handle)

where event-handle is a variable of omp_event_handle_t type and aff-modifier is one of the following:

 
iterator(iterators-definition)

The syntax of the task construct is as follows:

 
!$omp task [clause[ [,] clause] ... ] 
    loosely-structured-block 
!$omp end task

 
!$omp task [clause[ [,] clause] ... ] 
    strictly-structured-block 
[!$omp end task]

where clause is one of the following:

 
if([ task :] scalar-logical-expression) 
final(scalar-logical-expression) 
untied 
default(data-sharing-attribute) 
mergeable 
private(list) 
firstprivate(list) 
shared(list) 
in_reduction(reduction-identifier : list) 
depend([depend-modifier,] dependence-type : locator-list) 
priority(priority-value) 
allocate([allocator :] list) 
affinity([aff-modifier :] locator-list) 
detach(event-handle)

where event-handle is an integer variable of omp_event_handle_kindkind and aff-modifier is one of the following:

 
iterator(iterators-definition)

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

Description The task construct is a task generating construct. When a thread encounters a task construct, an explicit task is generated from the code for the associated structured block. The data environment of the task is created according to the data-sharing attribute clauses on the task construct, per-data environment ICVs, and any defaults that apply. The data environment of the task is destroyed when the execution code of the associated structured block is completed.

The encountering thread may immediately execute the task, or defer its execution. In the latter case, any thread in the team may be assigned the task. Completion of the task can be guaranteed using task synchronization constructs and clauses. If a task construct is encountered during execution of an outer task, the generated task region that corresponds to this construct is not a part of the outer task region unless the generated task is an included task.

If a detach clause is present on a task construct a new allow-completion event is created and connected to the completion of the associated task region. The original event-handle is updated to represent that allow-completion event before the task data environment is created. The event-handle is considered as if it was specified on a firstprivate clause. The use of a variable in a detach clause expression of a task construct causes an implicit reference to the variable in all enclosing constructs.

If no detach clause is present on a task construct the generated task is completed when the execution of its associated structured block is completed. If a detach clause is present on a task construct, the task is completed when the execution of its associated structured block is completed and the allow-completion event is fulfilled.

When an if clause is present on a task construct and the if clause expression evaluates to false, an undeferred task is generated, and the encountering thread must suspend the current task region, for which execution cannot be resumed until execution of the structured block that is associated with the generated task is completed. The use of a variable in an if clause expression of a task construct causes an implicit reference to the variable in all enclosing constructs.

When a final clause is present on a task construct and the final clause expression evaluates to true, the generated task is a final task. All task constructs that are encountered during execution of a final task generate final and included tasks. The use of a variable in a final clause expression of a task construct causes an implicit reference to the variable in all enclosing constructs. Encountering a task construct with the detach clause during the execution of a final task results in unspecified behavior.

The if clause expression and the final clause expression are evaluated in the context outside of the task construct, and no ordering of those evaluations is specified.

A thread that encounters a task scheduling point within the task region may temporarily suspend the task region. By default, a task is tied and its suspended task region can only be resumed by the thread that started its execution. If the untied clause is present on a task construct, any thread in the team can resume the task region after a suspension. The untied clause is ignored if the task is a final or an included task.

The task construct includes a task scheduling point in the task region of its generating task, immediately following the generation of the explicit task. Each explicit task region includes a task scheduling point at the end of its associated structured block.

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

The priority clause is a hint for the priority of the generated task. The priority-value is a non-negative integer expression that provides a hint for task execution order. Among all tasks ready to be executed, higher priority tasks (those with a higher numerical value in the priority clause expression) are recommended to execute before lower priority ones. The default priority-value when no priority clause is specified is zero (the lowest priority). If a value is specified in the priority clause that is higher than the max-task-priority-var ICV then the implementation will use the value of that ICV. A program that relies on the task execution order being determined by the priority-value may have unspecified behavior.

The affinity clause is a hint to indicate data affinity of the generated task. The task is recommended to execute close to the location of the list items. A program that relies on the task execution location being determined by this list may have unspecified behavior.

The list items that appear in the affinity clause may reference iterators defined by an iterators-definition that appears in the same clause. The list items that appear in the affinity clause may include array sections.

The list items that appear in the affinity clause may use shape-operators.

If a list item appears in an affinity clause then data affinity refers to the original list item.

Note – When storage is shared by an explicit task region, the programmer must ensure, by adding proper synchronization, that the storage does not reach the end of its lifetime before the explicit task region completes its execution.

Execution Model Events The task-create event occurs when a thread encounters a construct that causes a new task to be created. The event occurs after the task is initialized but before it begins execution or is deferred.

Tool Callbacks A thread dispatches a registered ompt_callback_task_create callback for each occurrence of a task-create event in the context of the encountering task. This callback has the type signature ompt_callback_task_create_t and the flags argument indicates the task types shown in Table 2.7.

Table 2.7:

ompt_callback_task_create Callback Flags Evaluation


Operation	Evaluates to true




(flags & ompt_task_explicit)	Always in the dispatched callback
(flags & ompt_task_undeferred)	If the task is an undeferred task
(flags & ompt_task_final)	If the task is a final task
(flags & ompt_task_untied)	If the task is an untied task
(flags & ompt_task_mergeable)	If the task is a mergeable task
(flags & ompt_task_merged)	If the task is a merged task

Restrictions Restrictions to the task construct are as follows:

A program must not depend on any ordering of the evaluations of the clauses of the task directive, or on any side effects of the evaluations of the clauses.
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.
At most one detach clause can appear on the directive.
If a detach clause appears on the directive, then a mergeable clause cannot appear on the same directive.

∙ A throw executed inside a task region must cause execution to resume within the same task region, and the same thread that threw the exception must catch it.

Cross References

Task scheduling constraints, see Section 2.12.6.
allocate clause, see Section 2.13.4.
if clause, see Section 2.18.
depend clause, see Section 2.19.11.
Data-sharing attribute clauses, Section 2.21.4.
in_reduction clause, see Section 2.21.5.6.
omp_fulfill_event, see Section 3.11.1.
ompt_callback_task_create_t, see Section 4.5.2.7.

[next] [prev] [prev-tail] [front] [up]