HOME
| 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

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

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the target construct is as follows:  

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

or  

 
!$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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

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

SVG-Viewer needed.

SVG-Viewer needed.

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

SVG-Viewer needed.

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:

Cross References