target Construct

| OPENMP API Specification: "Version 5.2 -- GIT rev 95b2e3a44"

13.8 target Construct


Name: target	Association: block
Category: executable	Properties: parallelism-generating, thread-limiting, exception-aborting, task-generating, device, device-aﬀecting, data-mapping, map-entering, map-exiting, context-matching

Clauses

allocate, defaultmap, depend, device, firstprivate, has_device_addr, if, in_reduction, is_device_ptr, map, nowait, private, thread_limit, uses_allocators

Binding

The binding task set for a target region is the generating task, which is the target task generated by the target construct. The target region binds to the corresponding target task region.

Semantics

The target construct provides a superset of the functionality provided by the target data directive, except for the use_device_ptr and use_device_addr clauses. The functionality added to the target directive is the inclusion of an executable region to be executed on a device. The target construct generates a target task. The generated task region encloses the target region. If a depend clause is present, it is associated with the target task. The device clause determines the device on which the target region executes. If the nowait clause is present, execution of the target task may be deferred. If the nowait clause is not present, the target task is an included task.

All clauses are evaluated when the target construct is encountered. The data environment of the target task is created according to the data-sharing and data-mapping attribute clauses on the target construct, per-data environment ICVs, and any default data-sharing attribute rules that apply to the target construct. If a variable or part of a variable is mapped by the target construct and does not appear as a list item in an in_reduction clause on the construct, the variable has a default data-sharing attribute of shared in the data environment of the target task. Assignment operations associated with mapping a variable (see Section 5.8.3) occur when the target task executes.

If the device clause is speciﬁed with the ancestor device-modiﬁer, the encountering thread waits for completion of the target region on the parent device before resuming. For any list item that appears in a map clause on the same construct, if the corresponding list item exists in the device data environment of the parent device, it is treated as if it has a reference count of positive inﬁnity.

When an if clause is present and the if clause expression evaluates to false, the eﬀect is as if a device clause that speciﬁes omp_initial_device as the device number is present, regardless of any other device clause on the directive.

If a procedure is explicitly or implicitly referenced in a target construct that does not specify a device clause in which the ancestor device-modiﬁer appears then that procedure is treated as if its name had appeared in an enter clause on a declare target directive.

If a variable with static storage duration is declared in a target construct that does not specify a device clause in which the ancestor device-modiﬁer appears then the named variable is treated as if it had appeared in a enter clause on a declare target directive.

If a list item in a map clause has a base pointer and it is a scalar variable with a predetermined data-sharing attribute of ﬁrstprivate (see Section 5.1.1), then on entry to the target region:

If the list item is not a zero-length array section, the corresponding private variable is initialized such that the corresponding list item in the device data environment can be accessed through the pointer in the target region.
If the list item is a zero-length array section , the corresponding private variable is initialized according to Section 5.8.6.

When an internal procedure is called in a target region, any references to variables that are host associated in the procedure have unspeciﬁed behavior.

Execution Model Events

Events associated with a target task are the same as for the task construct deﬁned in Section 12.5.

Events associated with the initial task that executes the target region are deﬁned in Section 12.8.

The target-submit-begin event occurs prior to initiating creation of an initial task on a target device for a target region.

The target-submit-end event occurs after initiating creation of an initial task on a target device for a target region.

The target-begin event occurs after creation of the target task and completion of all predecessor tasks that are not target tasks for the same device. The target-begin event is a target-task-begin event.

The target-end event occurs after all other events associated with the target construct.

Tool Callbacks

Callbacks associated with events for target tasks are the same as for the task construct deﬁned in Section 12.5; (ﬂags & ompt_task_target) always evaluates to true in the dispatched callback.

A thread dispatches a registered ompt_callback_target or ompt_callback_target_emi callback with ompt_scope_begin as its endpoint argument and ompt_target or ompt_target_nowait if the nowait clause is present as its kind argument for each occurrence of a target-begin event in that thread in the context of the target task on the host. Similarly, a thread dispatches a registered ompt_callback_target or ompt_callback_target_emi callback with ompt_scope_end as its endpoint argument and ompt_target or ompt_target_nowait if the nowait clause is present as its kind argument for each occurrence of a target-end event in that thread in the context of the target task on the host. These callbacks have type signature ompt_callback_target_t or ompt_callback_target_emi_t, respectively.

A thread dispatches a registered ompt_callback_target_submit_emi callback with ompt_scope_begin as its endpoint argument for each occurrence of a target-submit-begin event in that thread. Similarly, a thread dispatches a registered ompt_callback_target_submit_emi callback with ompt_scope_end as its endpoint argument for each occurrence of a target-submit-end event in that thread. These callbacks have type signature ompt_callback_target_submit_emi_t.

A thread dispatches a registered ompt_callback_target_submit callback for each occurrence of a target-submit-begin event in that thread. The callback occurs in the context of the target task and has type signature ompt_callback_target_submit_t.

Restrictions

Restrictions to the target construct are as follows:

Device-aﬀecting constructs, other than target constructs for which the ancestor device-modiﬁer is speciﬁed, must not be encountered during execution of a target region.
The result of an omp_set_default_device, omp_get_default_device, or omp_get_num_devices routine called within a target region is unspeciﬁed.
The eﬀect of an access to a threadprivate variable in a target region is unspeciﬁed.
If a list item in a map clause is a structure element, any other element of that structure that is referenced in the target construct must also appear as a list item in a map clause.
A list item in a data-sharing attribute clause that is speciﬁed on a target construct must not have the same base variable as a list item in a map clause on the construct.
A variable referenced in a target region but not the target construct that is not declared in the target region must appear in a declare target directive.
A map-type in a map clause must be to, from, tofrom or alloc.
If a device clause is speciﬁed with the ancestor device-modiﬁer, only the device, firstprivate, private, defaultmap, and map clauses may appear on the construct and no OpenMP constructs or calls to OpenMP API runtime routines are allowed inside the corresponding target region.
Memory allocators that do not appear in a uses_allocators clause cannot appear as an allocator in an allocate clause or be used in the target region unless a requires directive with the dynamic_allocators clause is present in the same compilation unit.
Any IEEE ﬂoating-point exception status ﬂag, halting mode, or rounding mode set prior to a target region is unspeciﬁed in the region.
Any IEEE ﬂoating-point exception status ﬂag, halting mode, or rounding mode set in a target region is unspeciﬁed upon exiting the region.
A program must not rely on the value of a function address in a target region except for assignments, comparisons to zero and indirect calls.

∙ An attached pointer must not be modiﬁed in a target region.

∙ The run-time type information (RTTI) of an object can only be accessed from the device on which it was constructed. ∙ Invoking a virtual member function of an object on a device other than the device on which the object was constructed results in unspeciﬁed behavior, unless the object is accessible and was constructed on the host device. ∙ If an object of polymorphic class type is destructed, virtual member functions of any previously existing corresponding objects in other device data environments must not be invoked.

∙ An attached pointer that is associated with a given pointer target must not become associated with a diﬀerent pointer target in a target region. ∙ If a list item in a map clause is an array section, and the array section is derived from a variable with a POINTER or ALLOCATABLE attribute then the behavior is unspeciﬁed if the corresponding list item’s variable is modiﬁed in the region. ∙ A reference to a coarray that is encountered on a non-host device must not be coindexed or appear as an actual argument to a procedure where the corresponding dummy argument is a coarray. ∙ If the allocation status of a mapped variable that has the ALLOCATABLE attribute is unallocated on entry to a target region, the allocation status of the corresponding variable in the device data environment must be unallocated upon exiting the region. ∙ If the allocation status of a mapped variable that has the ALLOCATABLE attribute is allocated on entry to a target region, the allocation status and shape of the corresponding variable in the device data environment may not be changed, either explicitly or implicitly, in the region after entry to it. ∙ If the association status of a list item with the POINTER attribute that appears in a map clause on the construct is associated upon entry to the target region, the list item must be associated with the same pointer target upon exit from the region. ∙ If the association status of a list item with the POINTER attribute that appears in a map clause on the construct is disassociated upon entry to the target region, the list item must be disassociated upon exit from the region. ∙ If the association status of a list item with the POINTER attribute that appears in a map clause on the construct is undeﬁned on entry to the target region, the association status of the list item must not be associated upon exit from the region. ∙ A program must not rely on the association status of a procedure pointer in a target region except for calls to the ASSOCIATED inquiry function without the optional proc-target argument, pointer assignments and indirect calls.

Cross References

ompt_callback_target_emi_t and ompt_callback_target_t, see Section 19.5.2.26
ompt_callback_target_submit_emi_t and ompt_callback_target_submit_t, see Section 19.5.2.28
allocate clause, see Section 6.6
defaultmap clause, see Section 5.8.7
depend clause, see Section 15.9.5
device clause, see Section 13.2
firstprivate clause, see Section 5.4.4
has_device_addr clause, see Section 5.4.9
if clause, see Section 3.4
in_reduction clause, see Section 5.5.10
is_device_ptr clause, see Section 5.4.7
map clause, see Section 5.8.3
nowait clause, see Section 15.6
private clause, see Section 5.4.3
target data directive, see Section 13.5
task directive, see Section 12.5
thread_limit clause, see Section 13.3
uses_allocators clause, see Section 6.8

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