2.12.5  target Construct

SummaryMap variables to a device data environment and execute the construct on that device.

Syntax

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

 
if([ target :] scalar-expression) 
device([ device-modifier :] 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) 
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)] ...])
       

 
ancestor 
device_num
       

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

 
if([ target :] scalar-logical-expression) 
device([ device-modifier :] 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) 
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)] ...])
       

 
ancestor 
device_num
       

BindingThe 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.

DescriptionThe 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 by 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.

All clauses are evaluated when the target construct is encountered. The data environment of the target task is created according to the data-sharing 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.19.7.1 on page 939) occur when the target task executes.

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 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 in the host data environment.

The is_device_ptr clause is used to indicate that a list item is a device pointer already in the device data environment and that it should be used directly. Support for device pointers created outside of OpenMP, specifically outside of the omp_target_alloc routine and the use_device_ptr clause, is implementation defined.

If a function (C, C++, Fortran) or subroutine (Fortran) is referenced in a target construct then that function or subroutine is treated as if its name 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.

Execution Model Events Events associated with a target task are the same as for the task construct defined in Section 2.10.1 on page 384.

Events associated with the initial task that executes the target region are defined in Section 2.10.5 on page 412.

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 event occurs prior to creating 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.10.1 on page 384; (flags & ompt_task_target) always evaluates to true in the dispatched callback.

A thread dispatches a registered ompt_callback_target callback with ompt_scope_begin as its endpoint argument and ompt_target 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 callback with ompt_scope_end as its endpoint argument and ompt_target 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.

A thread dispatches a registered ompt_callback_target_submit callback for each occurrence of a target-submit event in that thread. The callback has type signature ompt_callback_target_submit_t.

Restrictions

• 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 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.
• 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 in the device data environment.
• At most one device clause can appear on the directive. The device clause expression must evaluate to a non-negative integer value less than the value of omp_get_num_devices() or to the value of omp_get_initial_device().
• 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. ∙ The effect of invoking a virtual member function of an object on a device other than the device on which the object was constructed is implementation defined. ∙ 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.

  ∙ An attached pointer that is associated with a given pointer target must not become associated with a different pointer target in a target region. ∙ A list item that appears in an is_device_ptr clause must be a dummy argument that does not have the ALLOCATABLE, POINTER or VALUE attribute. ∙ 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.

Cross References

• default-device-var, see Section 2.5 on page 171.
• task construct, see Section 2.10.1 on page 384.
• task scheduling constraints, see Section 2.10.6 on page 415
• Memory allocators, see Section 2.11.2 on page 428.
• target data construct, see Section 2.12.2 on page 451.
• if Clause, see Section 2.15 on page 619.
• private and firstprivate clauses, see Section 2.19.4 on page 842.
• Data-Mapping Attribute Rules and Clauses, see Section 2.19.7 on page 934.
• omp_get_num_devices routine, see Section 3.2.36 on page 1127.
• omp_alloctrait_t and omp_alloctrait types, see Section 3.7.1 on page 1208.
• omp_set_default_allocator routine, see Section 3.7.4 on page 1214.
• omp_get_default_allocator routine, see Section 3.7.5 on page 1216.
• ompt_callback_target_t, see Section 4.5.2.26 on page 1384.
• ompt_callback_target_submit_t, Section 4.5.2.28 on page 1391.