OFFLOAD_TRANSFER

specifier

Can be any of the following:

• TARGET (target-name [:target-number])

• IF (if-specifier)

  An optional specifier. Include it to allow a test at execution time for whether or not the executable should try to offload the statement.

  You cannot specify both IF and MANDATORY.

• SIGNAL (tag)

  An optional specifier. Include it to enable asynchronous data transfer, meaning that data transfer is initiated, and the CPU can continue executing after initiating the offload. When you don't include it, data transfer is synchronous.

  SIGNAL is device specific; if you use this clause, you must specify a target-number >=0 in the TARGET clause.

• WAIT (tag [, tag, ...])

  An optional specifier. Include it to specify a wait for completion of a previously initiated asynchronous data transfer or asynchronous computation.

  WAIT is device specific; if you use this clause, you must specify a target-number >=0 in the TARGET clause.

• MANDATORY

  An optional specifier. Include it to specify that execution on the coprocessor is required. Execution on the CPU is not allowed. If the correct target hardware needed to run the offloaded code is not available on the system, the program fails with an error message.

  You cannot specify both MANDATORY and IF.

• offload-parameter [[,] offload-parameter]

  One or more data movement clauses (see below).

target-name

Is an identifier that represents the target. The only allowable target name is MIC.

target-number

(Required for SIGNAL and WAIT) Is an integer expression whose value is interpreted as follows:

If you don't specify this argument, the runtime system chooses whether to execute the code on the CPU or the coprocessor, and if multiple coprocessors are available, on which coprocessor.

For example, in a system with 4 coprocessors:

• Specifying 2 or 6 tells the runtime systems to use coprocessor 2 for the transfer, because both MOD(2,4) and MOD(6,4) equal 2.

• Specifying 1000 tells the runtime systems to use coprocessor 0 for the transfer, because MOD(1000,4) = 0.

if-specifier

Is a Boolean expression.

If the expression evaluates to true, then the data transfer specified by the directive occurs. If the specified target coprocessor is absent from the system or not available at that time because it is fully loaded, then no action is taken.

If the expression evaluates to false, then no action is taken and none of the other offload clauses have any effect.

tag

Is a scalar integer variable. It cannot have the ALLOCATABLE or the POINTER attribute.

When used with SIGNAL, tag is a memory reference and is associated with the data set in an asynchronous computation. tag can be used in subsequent WAIT clauses in other OFFLOAD directives.

When used with WAIT, tag is a memory reference; it is associated with a previously initiated asynchronous computation or asynchronous data transfer. Use the same tag that you specified in the SIGNAL specifier to start the asynchronous computation or data transfer with the OFFLOAD or OFFLOAD_TRANSFER directive.

offload-parameter

Can be any of the following data movement clauses:

• IN ( identifier[, identifier …] [: modifier[[,] modifier… ] ] )

• OUT ( identifier[, identifier …] [: modifier[,] modifier… ] ] )

• NOCOPY ( identifier[, identifier …] [: modifier[,] modifier… ] ] )

When a program runs in a heterogeneous environment, program variables are copied back and forth between the CPU and the target. The offload-parameter is a specification for controlling the direction in which variables are copied, and for pointers, the amount of data that is copied.

This specifier is required. It must not contain both an IN clause and an OUT clause.

An IN or OUT element-count-expr expression (see description below within modifier) is evaluated at a point in the program before the statement or clause in which it is used.

An array variable whose size is known from its declaration is copied in its entirety. If a subset of an array is to be processed, use the name of the starting element of the subset and the element-count-expr to transfer the array subset.

identifier

Is a variable, a subscripted variable, an array slice, or a component reference.

modifier

Is one of the following:

• LENGTH ( element-count-expr )

  where element-count-expr is an integer expression, computed at runtime. Use it with:

  • Integer pointer variables (not Fortran 90 POINTERs)

    Pointer variable values themselves are never copied across the host/target interface because there is no correspondence between the memory addresses of the host CPU and the target. Instead, objects that an integer pointer points to are copied to or from the target, and the value of the pointer variable is recreated. By default, a single element is copied.

    Use element-count-expr to specify how many elements pointed to should be considered as data. If the expression value is zero or negative, the program fails with an error message.

  • Arrays (including assumed-size)

    element-count-expr specifies a number of elements copied between the CPU and target.

    A Fortran array variable can be one of four major types: explicit-shape, assumed-shape, deferred-shape and assumed-size. The runtime descriptor for the first three types makes that array variable's size known at compile time or at runtime. The last dimension of an assumed-size array is the length of its variable.

    By default, the compiler copies explicit-shape, assumed-shape and deferred-shape arrays in their entirety. They do not need an element-count-expr. However, you can use an optional element-count-expr to specify the total number of elements to copy, which limits the number of elements copied back and forth in the last dimension of the array.

    You must specify an assumed-size array with an element-count-expr specification, because the compiler does not know the total size of the array. The value of the element-count-expr is the total number of elements of the array to be copied.

• ALLOC_IF ( condition ) | FREE_IF (condition )

  where condition is a Boolean expression.

  The ALLOC_IF modifier specifies a Boolean condition that controls whether the allocatable variables in the IN clause will be allocated a new block of memory on the target when the offload is executed on the target. If the expression evaluates to true, a new memory allocation is performed for each variable listed in the clause. If the condition evaluates to false, the existing allocated values on the target are reused. You must ensure that a block of memory of sufficient size has been previously allocated for the variables on the target by using a FREE_IF(.FALSE.) clause on an earlier offload.

  The FREE_IF modifier specifies a Boolean condition that controls whether to deallocate the memory allocated for the allocatable variables in an IN clause. If the expression evaluates to true, the memory pointed to by each variable listed in the clause is deallocated. If the condition evaluates to false, no action is taken on the memory pointed to by the variables in the list. A subsequent clause will be able to reuse the allocated memory (data persistence).

  The following are the default settings for ALLOC_IF and FREE_IF:

  	ALLOC_IF	FREE_IF
  IN	True	True
  INOUT	True	True
  OUT	True	True
  NOCOPY	False	False

  For more information, see Managing Memory Allocation for Pointer Variables.

• ALIGN (expression)

  where the value of expression should be a power of two.

  This modifier applies to pointer variables and requests the specified minimum alignment for pointer data allocated on the target.

• ALLOC (array-subscript-list)

  where array-subscript-list is a list of array section triplets that specifies a set of elements of an array that need allocation. The array-subscript-list takes the following form:

  start-element : end-element [ : stride] [ , start-element : end-element [ : stride] ]…

  This modifier can only be used in IN and OUT clauses and only one identifier must be listed in the clause. A one to one correspondence is established between the identifier in the IN or OUT clause and the base variable that will be allocated with array-subscript-list dimensions.

  When ALLOC is specified, the allocation on the target is the same shape as array-subscript-list. The variable being transferred or allocated must be the same variable used in the ALLOC modifier (identifier or into-identifier). Only unit strides are allowed in array-subscript-list. When array-subscript-list has rank greater than one, the second and subsequent subscript triplet must specify all elements at that dimension. Therefore, array-subscript-list must describe an array that is simply contiguous. (See CONTIGUOUS.)

  Data is transferred into that portion of the array specified by the IN or OUT clauses. Therefore, memory allocation and the data transfer can use separate array slice references.

  When the lower bound of the first dimension of array-subscript-list in the ALLOC is greater than the lower bound of the first dimension of identifier, then the memory allocation begins with that element. The memory below the lower bound is unallocated and should not be referenced by the program. This allows a smaller section of the array to be transferred to the target without requiring that the entire array be allocated.

  For more information, see Allocating Memory for Parts of Arrays.

• INTO (into-identitier)

  where into-identifier is a variable, a subscripted variable, an array slice, or a component reference with the same form, rank, dimensions, and kind type parameters as the identifier in the clause.

  This modifier can only be used in IN and OUT clauses and only one identifier must be listed in the clause. When INTO is specified, data can be transferred from one variable on the CPU to another on the target, and vice versa. This establishes a one to one correspondence between a single source variable and a single destination variable.

  You can specify ALLOC, ALLOC_IF, and FREE_IF modifiers along with the INTO modifier.

  When INTO is used in an IN clause, data is copied from the CPU object identifier to the target object into-identifier. If the ALLOC_IF, FREE_IF, or ALLOC modifier is specified, it applies only to the identifier in the IN clause.

  When INTO is used in an OUT clause, data is copied from the target object into-identifier to the CPU object identifier. If the ALLOC_IF, FREE_IF, or ALLOC modifier is specified, it applies only to the identifier in the OUT expression.

  When this modifier is used, the source expression generates a stream of elements to be copied into the memory range specified by the INTO expression.

  If overlap occurs between the source and destination variables, it causes undefined behavior (although with disjoint memories it will work as expected). No ordering can be assumed between transfers from different IN or OUT clauses.

  For more information, see Moving Data from One Variable to Another.