Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

ID 767251
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

MAP Clause

Parallel Directive Clause: Maps a variable from the data environment of the current task to the data environment of the device associated with the construct. This clause only applies to certain TARGET directives. This feature is only available for ifx.

Syntax

MAP ([[map-type-modifier[,]] map-type :] list)

map-type-modifier

Is one of the following:

ALWAYS

Specifies that initialization should always occur for the list items.

CLOSE

Suggests to the runtime system to allocate memory close to the target device.

MAPPER (mapper-identifier)

Specifies the name of an accessible user-defined mapper declared in a DECLARE MAPPER directive. If MAPPER is not present, it is as if MAPPER (DEFAULT) were specified.

The map behavior of a list item in a MAP clause with the same type as the type specified in the user-defined mapper is modified by a user-defined mapper.

If a list item does not also appear as a list item in a MAP clause with the PRESENT map-type-modifier in the same directive, the effect is to remove the list item from the MAP clause and apply the clauses specified in the user-defined mapper to the construct where the MAP clause appears.

References to var in the DECLARE MAPPER MAP clauses are replaced by the list item, and the map type is replaced with the final map type as determined by the table of final map types (see DECLARE MAPPER).

PRESENT

Causes an error to occur and program termination if any list item in the clause does not appear in the device data environment.

When the PRESENT map-type-modifier appears in a MAP clause, it takes precedence over all other MAP clauses in a directive. The behavior is as if the MAP clause specifying PRESENT appears lexically before any other MAP clauses in the directive.

map-type

Determines how a list item is initialized. Possible values are:

ALLOC

On entry to the outermost device region, each new corresponding list item has an undefined initial value.

DELETE

On exit from the device region, if the corresponding list item is present on the device, it is then deleted from the device.

FROM

On exit from the device region, the value of the corresponding list item is assigned to each original list item.

This is ignored for nested regions unless map-type-modifier ALWAYS is specified.

RELEASE

On exit from the outermost device region, the corresponding list item is deleted from the device.

TO

On entry to the device region, each new corresponding list item is initialized with the value of the original list item.

This is ignored for nested regions unless map-type-modifier ALWAYS is specified.

TOFROM

On entry to the device region, each new corresponding list item is initialized with the value of the original list item. On exit from the device region, the value of the corresponding list item is assigned to each original list item.

This is ignored for nested regions unless map-type-modifier ALWAYS is specified.

If a map-type is not specified, the default is TOFROM.

The map initialization and assignment are done as if by intrinsic assignment, that is, through bitwise copy.

list

Is the name of one or more variables, array sections, or common blocks that are accessible to the scoping unit. Subobjects cannot be specified. Each name must be separated by a comma, and a common block name must appear between slashes (/ /).

If a list item is an array section, it must specify contiguous storage.

A list item can appear in at most one of the TO, FROM, or TOFROM clauses. If a list item appears in an ALLOC clause, it cannot appear on a TO or TOFROM clause.

On entry to an outermost target region where this clause is used, for each original list item, a new corresponding list item is created on the device. On exit from the outermost target region, if the corresponding list item is present on the device, it is then deleted from the device.

At least one MAP clause must appear in a directive that allows the clause.

THREADPRIVATE variables cannot appear in a MAP clause.

For the TARGET ENTER DATA directive, map-type must be either TO or ALLOC.

For the TARGET EXIT DATA directive, map-type must be FROM, RELEASE, or DELETE.

For the TARGET and TARGET DATA directives, map-type must be TO, FROM, TOFROM, or ALLOC.

For the TARGET UPDATE directive, map-type must be TO or FROM.

If original and corresponding list items share storage, data races can result when intervening synchronization between tasks does not occur. If variables that share storage are mapped, it causes unspecified behavior.

Any variables within a TARGET MAP region that are not specified in a MAP clause are treated as shared variables within the region.

A list item must not contain any components that have the ALLOCATABLE attribute.

If the allocation status of a list item with the ALLOCATABLE attribute is unallocated upon entry to a target region, the list item must be unallocated upon exit from the region.

If the allocation status of a list item with the ALLOCATABLE attribute is allocated upon entry to a target region, the allocation status of the corresponding list item must not be changed and must not be reshaped in the region.

If an array section of an allocatable array is mapped and the size of the section is smaller than that of the whole array, the target region must not have any reference to the whole array.

A list item that is an array or an array section that has a type for which a user-defined mapper exists, is mapped as if the final map type is ALLOC, RELEASE, or DELETE. Then each element is mapped with the original map type, as if by a separate construct according to the user-defined mapper.

If a MAPPER map-type-modifier appears in the MAP clause, the type specified in the user-defined mapper must match the type of the list items in the MAP clause.

See Also