target Construct

| OPENMP API Specification: Version 5.1 November 2020

2.14.5 target Construct

Summary The target construct maps variables to a device data environment and executes the construct on that device.

Syntax

The syntax of the target construct is as follows:

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

where clause is one of the following:

 
if([ target :] scalar-expression) 
device([ device-modifier :] integer-expression) 
thread_limit(integer-expression) 
private(list) 
firstprivate(list) 
in_reduction(reduction-identifier : list) 
map([[map-type-modifier[,] [map-type-modifier[,] ...]] map-type: ] locator-list) 
is_device_ptr(list) 
has_device_addr(list) 
defaultmap(implicit-behavior[:variable-category]) 
nowait 
depend([depend-modifier,] dependence-type : locator-list) 
allocate([allocator :] list) 
uses_allocators(allocator[(allocator-traits-array)] 
               [,allocator[(allocator-traits-array)] ...])

and where device-modifier is one of the following:

 
ancestor 
device_num

and where allocator is an identifier of omp_allocator_handle_t type and allocator-traits-array is an identifier of const omp_alloctrait_t * type.

The syntax of the target construct is as follows:

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

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

where clause is one of the following:

 
if([ target :] scalar-logical-expression) 
device([ device-modifier :] scalar-integer-expression) 
thread_limit(scalar-integer-expression) 
private(list) 
firstprivate(list) 
in_reduction(reduction-identifier : list) 
map([[map-type-modifier[,] [map-type-modifier[,] ...]] map-type: ] locator-list) 
is_device_ptr(list) 
has_device_addr(list) 
defaultmap(implicit-behavior[:variable-category]) 
nowait 
depend([depend-modifier,] dependence-type : locator-list) 
allocate([allocator:] list) 
uses_allocators(allocator[(allocator-traits-array)] 
               [,allocator[(allocator-traits-array)] ...])

and where device-modifier is one of the following:

 
ancestor 
device_num

and where allocator is an integer expression of omp_allocator_handle_kindkind and allocator-traits-array is an array of type(omp_alloctrait) type.

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.

Description 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. That is, the target directive is an executable directive.

The target construct is a task generating construct. The generated task is a target task. The generated task region encloses the target region. The device clause determines the device on which the target region executes.

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 2.21.7.1) occur when the target task executes.

As described in Section 2.4.4.1, the target construct limits the number of threads that may participate in a contention group initiated by the initial thread by setting the value of the thread-limit-var ICV for the initial task to an implementation defined value greater than zero. If the thread_limit clause is specified, the number of threads will be less than or equal to the value specified in the clause.

If a device clause in which the device_numdevice-modifier appears is present on the construct, the device clause expression specifies the device number of the target device. If device-modifier does not appear in the clause, the behavior of the clause is as if device-modifier is device_num.

If a device clause in which the ancestordevice-modifier appears is present on the target construct and the device clause expression evaluates to 1, execution of the target region occurs on the parent device of the enclosing target region. If the target construct is not encountered in a target region, the current device is treated as the parent device. 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 infinity.

If no device clause is present, the behavior is as if the device clause appears without a device-modifier and with an expression equal to the value of the default-device-var ICV.

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.

If a depend clause is present, it is associated with the target task.

When an if clause is present and the if clause expression evaluates to false, the target region is executed by the host device.

The has_device_addr clause indicates that its list items already have device addresses and therefore they may be directly accessed from a target device. If the device address of a list item is not for the device on which the target region executes, accessing the list item inside the region results in unspecified behavior. The list items may include array sections.

The is_device_ptr clause indicates that its list items are device pointers. Inside the target construct, each list item is privatized and the new list item is initialized to the device address to which the original list item refers. Support for device pointers created outside of OpenMP, specifically outside of any OpenMP mechanism that returns a device pointer, is implementation defined.

The is_device_ptr clause indicates that its list items are device pointers if they are of type C_PTR. Inside the target construct, each list item of type C_PTR is privatized and the new list item is initialized to the device address to which the original list item refers. Support for device pointers created outside of OpenMP, specifically outside of any OpenMP mechanism that returns a device pointer, is implementation defined. For any list item in an is_device_ptr clause that is not of type C_PTR, the behavior is as if the list item appeared in a has_device_addr clause. Support for such list items in an is_device_ptr clause is deprecated.

If a function (C, C++, Fortran) or subroutine (Fortran) is referenced in a target construct that does not specify a device clause in which the ancestordevice-modifier appears then that function or subroutine is treated as if its name had appeared in a to 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 ancestordevice-modifier appears then the named variable is treated as if it had appeared in a to clause on a declare target directive.

Each memory allocator specified in the uses_allocators clause will be made available in the target region. For each non-predefined allocator that is specified, a new allocator handle will be associated with an allocator that is created with the specified traits as if by a call to omp_init_allocator at the beginning of the target region. Each non-predefined allocator will be destroyed as if by a call to omp_destroy_allocator at the end of the target region.

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 firstprivate (see Section 2.21.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 2.21.7.2.

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

Execution Model Events Events associated with a target task are the same as for the task construct defined in Section 2.12.1.

Events associated with the initial task that executes the target region are defined in Section 2.12.5.

The target-begin event occurs when a thread enters a target region.

The target-end event occurs when a thread exits a target region.

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.

Tool Callbacks Callbacks associated with events for target tasks are the same as for the task construct defined in Section 2.12.1; (flags & 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:

If a target update, target data, target enter data, or target exit data construct is encountered during execution of a target region, the behavior is unspecified.
The result of an omp_set_default_device, omp_get_default_device, or omp_get_num_devices routine called within a target region is unspecified.
The effect of an access to a threadprivate variable in a target region is unspecified.
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 cannot appear in both a map clause and a data-sharing attribute clause on the same target 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.
At most one defaultmap clause for each category can appear on the directive.
At most one nowait clause can appear on the directive.
At most one if clause can appear on the directive.
A map-type in a map clause must be to, from, tofrom or alloc.
A list item that appears in an is_device_ptr clause must be a valid device pointer for the device data environment.
A list item that appears in a has_device_addr clause must have a valid device address for the device data environment.
A list item may not be specified in both an is_device_ptr clause and a has_device_addr clause on the directive.
A list item that appears in an is_device_ptr or a has_device_addr clause must not be specified in any data-sharing attribute clause on the same target construct.
At most one device clause can appear on the directive. The device clause expression must evaluate to a non-negative integer value that is less than or equal to the value of omp_get_num_devices().
If a device clause in which the ancestor device-modifier appears is present on the construct, then the following restrictions apply:
- A requires directive with the reverse_offload clause must be specified;
- The device clause expression must evaluate to 1;
- Only the device, firstprivate, private, defaultmap, and map clauses may appear on the construct;
- 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.
Memory allocators that appear in a uses_allocators clause cannot appear in other data-sharing attribute clauses or data-mapping attribute clauses in the same construct.
Predefined allocators appearing in a uses_allocators clause cannot have traits specified.
Non-predefined allocators appearing in a uses_allocators clause must have traits specified.
Arrays that contain allocator traits that appear in a uses_allocators clause must be constant arrays, have constant values and be defined in the same scope as the construct in which the clause appears.
Any IEEE floating-point exception status flag, halting mode, or rounding mode set prior to a target region is unspecified in the region.
Any IEEE floating-point exception status flag, halting mode, or rounding mode set in a target region is unspecified upon exiting the region.

∙ An attached pointer must not be modified in a target region.

∙ A list item that appears in an is_device_ptr clause must have a type of pointer or array.

∙ A list item that appears in an is_device_ptr clause must have a type of pointer, array, reference to pointer or reference to array. ∙ A throw executed inside a target region must cause execution to resume within the same target region, and the same thread that threw the exception must catch it. ∙ The run-time type information (RTTI) of an object can only be accessed from the device on which it was constructed.

∙ An attached pointer that is associated with a given pointer target must not become associated with a different 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 unspecified if the corresponding list item’s variable is modified 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 disassociated or undefined on entry to the target region and if the list item is associated with a pointer target inside the target region, the pointer association status must become disassociated before the end the region.

Cross References

default-device-var, see Section 2.4.
task construct, see Section 2.12.1.
task scheduling constraints, see Section 2.12.6
Memory allocators, see Section 2.13.2.
target data construct, see Section 2.14.2.
if clause, see Section 2.18.
private and firstprivate clauses, see Section 2.21.4.
Data-Mapping Attribute Rules and Clauses, see Section 2.21.7.
omp_get_num_devices routine, see Section 3.7.4.
omp_alloctrait_t and omp_alloctrait types, see Section 3.13.1.
omp_set_default_allocator routine, see Section 3.13.4.
omp_get_default_allocator routine, see Section 3.13.5.
ompt_callback_target_t or ompt_callback_target_emi_t callback type, see Section 4.5.2.26.
ompt_callback_target_submit_t or ompt_callback_target_submit_emi_t callback type, Section 4.5.2.28.

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