HOME
| OPENMP API Specification: Version 5.0 November 2018

2.12.5  target Construct

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

Syntax

SVG-Viewer needed.

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) 
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)] ...])  

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.

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the target construct is as follows:  

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

where clause is one of the following:  

 
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)] ...])  

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.19.1.1 on page 777), then on entry to the target region:

SVG-Viewer needed.

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

Cross References