TARGET / END TARGET

Purpose

The TARGET directive instructs the compiler to generate a target task, that is, to map variables to a device data environment and to execute the enclosed block of code on that device.

Use the TARGET and END TARGET directives to define a target region, which is a block of computation that operates within a distinct data environment and is intended to be offloaded onto a parallel computation device during execution.

Required options

-qsmp and -qoffload

Syntax


           .-+---+-------------.   
           | '-,-'             |   
           V                   |   
>>-TARGET----+---------------+-+-------------------------------><
             '-target_clause-'


>>-block-------------------------------------------------------><


>>-END TARGET--------------------------------------------------><

where target_clause is:


>>-+-defaultmap_clause----+------------------------------------><
   +-depend_clause--------+   
   +-device_clause--------+   
   +-firstprivate_clause--+   
   +-if_clause------------+   
   +-is_device_ptr_clause-+   
   +-map_clause-----------+   
   +-nowait_clause--------+   
   '-private_clause-------'

defaultmap_clause

Changes the default implicit mapping rule from FIRSTPRIVATE to TOFROM for scalar variables. The syntax is DEFAULTMAP(TOFROM:SCALAR). For more information about implicit mapping, see the Rules section.

depend_clause

Establishes scheduling dependences between the target task and sibling tasks that share list items. The syntax is DEPEND(dependence-type:list). The dependence-type can be IN, OUT, or INOUT. Data variables in list are separated by commas.

If dependence-type is IN or INOUT, for each list item that has the same storage location as a list item in a depend clause of a sibling task with the OUT or INOUT dependence type, a scheduling dependence for the target task on the sibling task is created.
If dependence-type is OUT or INOUT, for each list item that has the same storage location as a list item in a depend clause of a sibling task with the IN, OUT, or INOUT dependence type, a scheduling dependence for the target task on the sibling task is created.

device_clause

Creates the data environment on the device with the designated ID. The syntax is DEVICE(scalar-integer-expression). The scalar-integer-expression must evaluate to a non-negative integer value that is less than the value of the omp_get_num_devices function.

firstprivate_clause

Declares the listed data variables to be private to the target task and shared by every thread team that runs the region. A new item is created for each list item that is referenced by the target task as if there was an implied declaration within the statement block. Each new private object is initialized with the value of the original variable.

For more information, see FIRSTPRIVATE.

if_clause

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 syntax is IF([TARGET:]logical-expression).

is_device_ptr_clause

Indicates that the listed data variables are device pointers that exist within the device data environment. Any listed data variable must be a dummy argument. The syntax is IS_DEVICE_PTR(list).

map_clause

Specifies the listed data variables to be explicitly mapped from the original variables in the host data environment to the corresponding variables in the device data environment of the device specified by the construct. The syntax is MAP([[map-type-modifier[,]]map-type:]list).

map-type can be TO, FROM, TOFROM, or ALLOC.

If a list item does not exist in the device data environment, a new item is created in the device data environment.
- If map-type is TO or TOFROM, this new item is initialized with the value of the original list item in list in the host data environment.
- If map-type is FROM or ALLOC, the initial value of the list item in the device data environment is undefined.
On exit from the target region, if storage for the list item was created in the device data environment when this construct was first encountered, the list item is deallocated from the device data environment. Furthermore, if map-type is FROM or TOFROM, the original list item is updated with the current value of the corresponding list item in the device data environment before the list item in the device data environment is deallocated.
If the list item exists in the device data environment when the construct is encountered, the allocation count of the item in the device environment changes as follows:
- It is incremented by one at the start of the construct
- It is decremented by one at the end of the construct.

map-type-modifier is ALWAYS. If this modifier is present, the following rules apply:

If map-type is TO or TOFROM, the value of the original list item is always copied to the device environment, regardless of whether a new item was created in the device data environment for the list item.
If map-type is FROM or TOFROM, the value of the list item is always copied from the device environment to the original list item, regardless of whether the device list item will be deallocated at termination of the construct.

You can specify associate names in map_clause.

nowait_clause

Eliminates the implicit barrier so the parent task can make progress even if the target task is not yet completed. By default, an implicit barrier exists at the end of the target construct, which ensures the parent task cannot continue until the target task is completed. The syntax is NOWAIT.

private_clause

Declares the listed data variables to be private to the target and shared by every thread team that runs the region. A new item is created for each list item that is referenced by the target task.

For more information, see PRIVATE.

reduction_clause

Specifies that for each data variable in list, a private copy is created and initialized based on the reduction-identifier. At the end of the region, the original data variable is updated with the values of the private copies using a combiner based on the reduction-identifier.

The syntax is REDUCTION(reduction-identifier:list). Scalar variables are supported in list. Items in list are separated by commas. reduction-identifier is either one of the following operators: +, -, *, .and., .or., .eqv., .neqv., or one of the following intrinsic procedure names: max, min, iand, ior, ieor.

Limitations: The reduction clause on the TARGET directive is supported only in the form of combined constructs, such as TARGET PARALLEL DO or TARGET TEAMS DISTRIBUTE PARALLEL DO.

block: Represents the block of code to be executed in the device data environment.

Rules

Execution of the target region depends on the successful offloading of the region to the device environment. If a target region cannot be successfully offloaded to a device, the target region is executed within the host environment.

Nesting of target regions, either dynamically or statically, is not allowed.

The data environment of a target region is defined by the implicit and explicit mapping of variables between the host and device:

Implicit mapping: The compiler determines which variables must be mapped to, from, or both to and from the device data environment. Scalar variables that are not explicitly mapped are implicitly mapped as FIRSTPRIVATE unless DEFAULTMAP(TOFROM:SCALAR) is specified.
Explicit mapping: You can use the MAP clause on the target region to explicitly list variables to be mapped to, from, or both to and from the device data environment.

A listed data variable cannot appear in both a data-sharing clause and the map clause on the same target construct.

Examples

INTEGER :: x
x = 1
!$OMP TARGET MAP(TOFROM: x)
  x = x + 1
!$OMP END TARGET
WRITE(*,*) "After target region, x = ", x

The integer x is declared in the host environment, and its initial value is set to 1 on the host. The target region is declared with explicit map type TOFROM of x, so the storage for x is allocated on the device and the device copy of x is initialized to 1. Within the target region, the value of the copy of x on the device is incremented by 1. At the end of the target region, x is mapped back to the host environment according to the map type TOFROM, and the host prints the value of x to be 2.

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum