Data-Mapping Attribute Rules, Clauses, and Directives

| OPENMP API Specification: Version 5.0 November 2018

2.19.7 Data-Mapping Attribute Rules, Clauses, and Directives

This section describes how the data-mapping and data-sharing attributes of any variable referenced in a target region are determined. When specified, explicit data-sharing attributes, map or is_device_ptr clauses on target directives determine these attributes. Otherwise, the first matching rule from the following implicit data-mapping rules applies for variables referenced in a target construct that are not declared in the construct and do not appear in data-sharing attribute, map or is_device_ptr clauses.

If a variable appears in a to or link clause on a declare target directive then it is treated as if it had appeared in a map clause with a map-type of tofrom.
If a list item appears in a reduction, lastprivate or linear clause on a combined target construct then it is treated as if it also appears in a map clause with a map-type of tofrom.
If a list item appears in an in_reduction clause on a target construct then it is treated as if it also appears in a map clause with a map-type of tofrom and a map-type-modifier of always.
If a defaultmap clause is present for the category of the variable and specifies an implicit behavior other than default, the data-mapping attribute is determined by that clause.

∙ If the target construct is within a class non-static member function, and a variable is an accessible data member of the object for which the non-static data member function is invoked, the variable is treated as if the this[:1] expression had appeared in a map clause with a map-type of tofrom. Additionally, if the variable is of a type pointer or reference to pointer, it is also treated as if it has appeared in a map clause as a zero-length array section. ∙ If the this keyword is referenced inside a target construct within a class non-static member function, it is treated as if the this[:1] expression had appeared in a map clause with a map-type of tofrom.

∙ A variable that is of type pointer is treated as if it is the base pointer of a zero-length array section that appeared as a list item in a map clause.

∙ A variable that is of type reference to pointer is treated as if it had appeared in a map clause as a zero-length array section.
If a variable is not a scalar then it is treated as if it had appeared in a map clause with a map-type of tofrom.

∙ If a scalar variable has the TARGET, ALLOCATABLE or POINTER attribute then it is treated as if it has appeared in a map clause with a map-type of tofrom.
If none of the above rules applies then a scalar variable is not mapped, but instead has an implicit data-sharing attribute of mapped, but instead has an implicit data-sharing attribute of firstprivate (see Section 2.19.1.1 on page 777).

2.19.7.1 map Clause

SummaryThe map clause specifies how an original list item is mapped from the current task’s data environment to a corresponding list item in the device data environment of the device identified by the construct.

Syntax

The syntax of the map clause is as follows:

 
map([ [map-type-modifier[,] [map-type-modifier[,] ...] map-type : ] locator-list)

where map-type is one of the following:

 
to 
from 
tofrom 
alloc 
release 
delete

and map-type-modifier is one of the following:

 
always 
close 
mapper(mapper-identifier)

DescriptionThe list items that appear in a map clause may include array sections and structure elements. The map-type and map-type-modifier specify the effect of the map clause, as described below.

For a given construct, the effect of a map clause with the to, from, or tofrommap-type is ordered before the effect of a map clause with the alloc, release, or deletemap-type. If a mapper is specified for the type being mapped, or explicitly specified with the mappermap-type-modifier, then the effective map-type of a list item will be determined according to the rules of map-type decay.

If a mapper is specified for the type being mapped, or explicitly specified with the mapper map-type-modifier, then all map clauses that appear on the declare mapper directive are treated as though they appeared on the construct with the map clause. Array sections of a mapper type are mapped as normal, then each element in the array section is mapped according to the rules of the mapper.

If a list item in a map clause is a variable of structure type then it is treated as if each structure element contained in the variable is a list item in the clause.

If a list item in a map clause is a derived type variable then it is treated as if each component is a list item in the clause.

Each pointer component that is a list item that results from a mapped derived type variable is treated as if its association status is undefined, unless the pointer component appears as another list item or as the base pointer of another list item in a map clause on the same construct.

If a list item in a map clause is a structure element then all other structure elements of the containing structure variable form a structure sibling list. The map clause and the structure sibling list are associated with the same construct. If a corresponding list item of the structure sibling list item is present in the device data environment when the construct is encountered then:

If the structure sibling list item does not appear in a map clause on the construct then:
- If the construct is a target, target data, or target enter data construct then the structure sibling list item is treated as if it is a list item in a map clause on the construct with a map-type of alloc.
- If the construct is target exit data construct, then the structure sibling list item is treated as if it is a list item in a map clause on the construct with a map-type of release.
  
  – If the structure sibling list item is a pointer then it is treated as if its association status is undefined, unless it appears as the base pointer of another list item in a map clause on the same construct.
If the map clause in which the structure element appears as a list item has a map-type of delete and the structure sibling list item does not appear as a list item in a map clause on the construct with a map-type of delete then the structure sibling list item is treated as if it is a list item in a map clause on the construct with a map-type of delete.

If item₁ is a list item in a map clause, and item₂ is another list item in a map clause on the same construct that has a base pointer that is, or is part of, item₁, then:

If the map clause(s) appear on a target, target data, or target enter data construct, then on entry to the corresponding region the effect of the map clause on item₁ is ordered to occur before the effect of the map clause on item₂.
If the map clause(s) appear on a target, target data, or target exit data construct then on exit from the corresponding region the effect of the map clause on item₂ is ordered to occur before the effect of the map clause on item₁.

If a list item in a map clause is an associated pointer and the pointer is not the base pointer of another list item in a map clause on the same construct, then it is treated as if its pointer target is implicitly mapped in the same clause. For the purposes of the map clause, the mapped pointer target is treated as if its base pointer is the associated pointer.

If a list item in a map clause has a base pointer, and a pointer variable is present in the device data environment that corresponds to the base pointer when the effect of the map clause occurs, then if the corresponding pointer or the corresponding list item is created in the device data environment on entry to the construct, then:

1.: The corresponding pointer variable is assigned an address such that the corresponding list item can be accessed through the pointer in a target region.

1.: The corresponding pointer variable is associated with a pointer target that has the same rank and bounds as the pointer target of the original pointer, such that the corresponding list item can be accessed through the pointer in a target region.

2.: The corresponding pointer variable becomes an attached pointer for the corresponding list item.
1.: If the original base pointer and the corresponding attached pointer share storage, then the original list item and the corresponding list item must share storage.

If a lambda is mapped explicitly or implicitly, variables that are captured by the lambda behave as follows:

the variables that are of pointer type are treated as if they had appeared in a map clause as zero-length array sections; and
the variables that are of reference type are treated as if they had appeared in a map clause.

If a member variable is captured by a lambda in class scope, and the lambda is later mapped explicitly or implicitly with its full static type, the this pointer is treated as if it had appeared on a map clause.

The original and corresponding list items may share storage such that writes to either item by one task followed by a read or write of the other item by another task without intervening synchronization can result in data races.

If the map clause appears on a target, target data, or target enter data construct then on entry to the region the following sequence of steps occurs as if performed as a single atomic operation:

1.

If a corresponding list item of the original list item is not present in the device data environment, then:

a): A new list item with language-specific attributes is derived from the original list item and created in the device data environment;
b): The new list item becomes the corresponding list item of the original list item in the device data environment;
c): The corresponding list item has a reference count that is initialized to zero; and
d): The value of the corresponding list item is undefined;

2.

If the corresponding list item’s reference count was not already incremented because of the effect of a map clause on the construct then:

a): The corresponding list item’s reference count is incremented by one;

3.

If the corresponding list item’s reference count is one or the alwaysmap-type-modifier is present, and if the map-type is to or tofrom, then:

a): For each part of the list item that is an attached pointer, that part of the corresponding list item will have the value that it had immediately prior to the effect of the map clause; and

a): For each part of the list item that is an attached pointer, that part of the corresponding list item, if associated, will be associated with the same pointer target that it was associated with immediately prior to the effect of the map clause.

b): For each part of the list item that is not an attached pointer, the value of that part of the original list item is assigned to that part of the corresponding list item.

Note – If the effect of the map clauses on a construct would assign the value of an original list item to a corresponding list item more than once, then an implementation is allowed to ignore additional assignments of the same value to the corresponding list item.

In all cases on entry to the region, concurrent reads or updates of any part of the corresponding list item must be synchronized with any update of the corresponding list item that occurs as a result of the map clause to avoid data races.

If the map clause appears on a target, target data, or target exit data construct and a corresponding list item of the original list item is not present in the device data environment on exit from the region then the list item is ignored. Alternatively, if the map clause appears on a target, target data, or target exit data construct and a corresponding list item of the original list item is present in the device data environment on exit from the region, then the following sequence of steps occurs as if performed as a single atomic operation:

1.

If the map-type is not delete and the corresponding list item’s reference count is finite and was not already decremented because of the effect of a map clause on the construct then:

a): The corresponding list item’s reference count is decremented by one;

2.

If the map-type is delete and the corresponding list item’s reference count is finite then:

a): The corresponding list item’s reference count is set to zero;

3.

If the map-type is from or tofrom and if the corresponding list item’s reference count is zero or the alwaysmap-type-modifier is present then:

a): For each part of the list item that is an attached pointer, that part of the original list item will have the value that it had immediately prior to the effect of the map clause;

a): For each part of the list item that is an attached pointer, that part of the corresponding list item, if associated, will be associated with the same pointer target with which it was associated immediately prior to the effect of the map clause; and

b): For each part of the list item that is not an attached pointer, the value of that part of the corresponding list item is assigned to that part of the original list item; and

4.

If the corresponding list item’s reference count is zero then the corresponding list item is removed from the device data environment.

Note – If the effect of the map clauses on a construct would assign the value of a corresponding list item to an original list item more than once, then an implementation is allowed to ignore additional assignments of the same value to the original list item.

In all cases on exit from the region, concurrent reads or updates of any part of the original list item must be synchronized with any update of the original list item that occurs as a result of the map clause to avoid data races.

If a single contiguous part of the original storage of a list item with an implicit data-mapping attribute has corresponding storage in the device data environment prior to a task encountering the construct that is associated with the map clause, only that part of the original storage will have corresponding storage in the device data environment as a result of the map clause.

If a list item with an implicit data-mapping attribute does not have any corresponding storage in the device data environment prior to a task encountering the construct associated with the map clause, and one or more contiguous parts of the original storage are either list items or base pointers to list items that are explicitly mapped on the construct, only those parts of the original storage will have corresponding storage in the device data environment as a result of the map clauses on the construct.

If a new list item is created then a new list item of the same type, with automatic storage duration, is allocated for the construct. The size and alignment of the new list item are determined by the static type of the variable. This allocation occurs if the region references the list item in any statement. Initialization and assignment of the new list item are through bitwise copy.

If a new list item is created then a new list item of the same type, type parameter, and rank is allocated. The new list item inherits all default values for the type parameters from the original list item. The value of the new list item becomes that of the original list item in the map initialization and assignment.

If the allocation status of the original list item with the ALLOCATABLE attribute is changed in the host device data environment and the corresponding list item is already present in the device data environment, the allocation status of the corresponding list item is unspecified until a mapping operation is performed with a map clause on entry to a target, target data, or target enter data region.

The map-type determines how the new list item is initialized.

If a map-type is not specified, the map-type defaults to tofrom.

The closemap-type-modifier is a hint to the runtime to allocate memory close to the target device.

Execution Model EventsThe target-map event occurs when a thread maps data to or from a target device. The target-data-op event occurs when a thread initiates a data operation on a target device.

Tool Callbacks A thread dispatches a registered ompt_callback_target_map callback for each occurrence of a target-map event in that thread. The callback occurs in the context of the target task and has type signature ompt_callback_target_map_t.

A thread dispatches a registered ompt_callback_target_data_op callback for each occurrence of a target-data-op event in that thread. The callback occurs in the context of the target task and has type signature ompt_callback_target_data_op_t.

RestrictionsThe restrictions to the map clause are as follows:

A list item cannot appear in both a map clause and a data-sharing attribute clause on the same construct unless the construct is a combined construct.
Each of the map-type-modifier modifiers can appear at most once on the map clause.

∙ List items of the map clauses on the same construct must not share original storage unless they are the same lvalue expression or array section.
If a list item is an array section, it must specify contiguous storage.
If multiple list items are explicitly mapped on the same construct and have the same containing array or have base pointers that share original storage, and if any of the list items do not have corresponding list items that are present in the device data environment prior to a task encountering the construct, then the list items must refer to the same array elements of either the containing array or the implicit array of the base pointers.
If any part of the original storage of a list item with an explicit data-mapping attribute has corresponding storage in the device data environment prior to a task encountering the construct associated with the map clause, all of the original storage must have corresponding storage in the device data environment prior to the task encountering the construct.
If a list item is an element of a structure, and a different element of the structure has a corresponding list item in the device data environment prior to a task encountering the construct associated with the map clause, then the list item must also have a corresponding list item in the device data environment prior to the task encountering the construct.
A list item must have a mappable type.
threadprivate variables cannot appear in a map clause.
If a mapper map-type-modifier is specified, its type must match the type of the list-items passed to that map clause.
Memory spaces and memory allocators cannot appear as a list item in a map clause.

∙ If the type of a list item is a reference to a type T then the reference in the device data environment is initialized to refer to the object in the device data environment that corresponds to the object referenced by the list item. If mapping occurs, it occurs as though the object were mapped through a pointer with an array section of type T and length one. ∙ No type mapped through a reference can contain a reference to its own type, or any references to types that could produce a cycle of references. ∙ If the list item is a lambda, any pointers and references captured by the lambda must have the corresponding list item in the device data environment prior to the task encountering the construct.

∙ A list item cannot be a variable that is a member of a structure with a union type. ∙ A bit-field cannot appear in a map clause. ∙ A pointer that has a corresponding attached pointer must not be modified for the duration of the lifetime of the list item to which the corresponding pointer is attached in the device data environment.

List items of the map clauses on the same construct must not share original storage unless they are the same variable or array section.
A pointer that has a corresponding attached pointer and is associated with a given pointer target must not become associated with a different pointer target for the duration of the lifetime of the list item to which the corresponding pointer is attached in the device data environment.
If the allocation status of a list item or any subobject of the list item with the ALLOCATABLE attribute is unallocated upon entry to a target region, the list item or any subobject of the corresponding list item must be unallocated upon exit from the region.
If the allocation status of a list item or any subobject of the list item with the ALLOCATABLE attribute is allocated upon entry to a target region, the allocation status of the corresponding list item or any subobject of the corresponding list item must not be changed and must not be reshaped in the region.
If an array section is mapped and the size of the section is smaller than that of the whole array, the behavior of referencing the whole array in the target region is unspecified.
A list item must not be a whole array of an assumed-size array.
If the association status of a list item with the POINTER attribute is associated upon entry to a target region, the list item must be associated with the same pointer target upon exit from the region.
If the association status of a list item with the POINTER attribute is disassociated upon entry to a target region, the list item must be disassociated upon exit from the region.
If the association status of a list item with the POINTER attribute is undefined upon entry to a target region, the list item must be undefined upon exit from the region.
If the association status of a list item with the POINTER attribute is disassociated or undefined on entry and if the list item is associated with a pointer target inside a target region, then the pointer association status must become disassociated before the end of the region.

Cross References

ompt_callback_target_data_op_t, see Section 4.5.2.25 on page 1381.
ompt_callback_target_map_t, see Section 4.5.2.27 on page 1388.

2.19.7.2 defaultmap Clause

Summary The defaultmap clause explicitly determines the data-mapping attributes of variables that are referenced in a target construct for which the data-mapping attributes would otherwise be implicitly determined (see Section 2.19.7 on page 934).

Syntax

The syntax of the defaultmap clause is as follows:

 
  defaultmap(implicit-behavior[:variable-category])

Where implicit-behavior is one of:

 
  alloc 
  to 
  from 
  tofrom 
  firstprivate 
  none 
  default

and variable-category is one of:

 
  scalar 
  aggregate 
  pointer

and variable-category is one of:

 
  scalar 
  aggregate 
  allocatable 
  pointer

DescriptionThe defaultmap clause sets the implicit data-mapping attribute for all variables referenced in the construct. If variable-category is specified, the effect of the defaultmap clause is as follows:

If variable-category is scalar, all scalar variables of non-pointer type or all non-pointer non-allocatable scalar variables that have an implicitly determined data-mapping or data-sharing attribute will have a data-mapping or data-sharing attribute specified by implicit-behavior.
If variable-category is aggregate or allocatable, all aggregate or allocatable variables that have an implicitly determined data-mapping or data-sharing attribute will have a data-mapping or data-sharing attribute specified by implicit-behavior.
If variable-category is pointer, all variables of pointer type or with the POINTER attribute that have implicitly determined data-mapping or data-sharing attributes will have a data-mapping or data-sharing attribute specified by implicit-behavior. The zero-length array section and attachment that are otherwise applied to an implicitly mapped pointer are only provided for the default behavior.

If no variable-category is specified in the clause then implicit-behavior specifies the implicitly determined data-mapping or data-sharing attribute for all variables referenced in the construct. If implicit-behavior is none, each variable referenced in the construct that does not have a predetermined data-sharing attribute and does not appear in a to or link clause on a declare target directive must be listed in a data-mapping attribute clause, a data-sharing attribute clause (including a data-sharing attribute clause on a combined construct where target is one of the constituent constructs), or an is_device_ptr clause. If implicit-behavior is default, then the clause has no effect for the variables in the category specified by variable-category.

2.19.7.3 declare mapper Directive

Summary The declare mapper directive declares a user-defined mapper for a given type, and may define a mapper-identifier that can be used in a map clause. The declare mapper directive is a declarative directive.

Syntax

The syntax of the declare mapper directive is as follows:

 
#pragma omp declare mapper([mapper-identifier:]type var) \ 
            [clause[ [,] clause] ... ] new-line

The syntax of the declare mapper directive is as follows:

 
!$omp declare mapper([mapper-identifier:] type :: var) & 
      [clause[ [,] clause] ... ]

where:

mapper-identifier is a base-language identifier or default
type is a valid type in scope
var is a valid base-language identifier
clause is map([[map-type-modifier[,] [map-type-modifier[,] ...]] map-type: ] list) , where map-type is one of the following:
- alloc
- to
- from
- tofrom
and where map-type-modifier is one of the following:
- always
- close

DescriptionUser-defined mappers can be defined using the declare mapper directive. The type and the mapper-identifier uniquely identify the mapper for use in a map clause later in the program. If the mapper-identifier is not specified, then default is used. The visibility and accessibility of this declaration are the same as those of a variable declared at the same point in the program. The variable declared by var is available for use in all map clauses on the directive, and no part of the variable to be mapped is mapped by default.

The default mapper for all types T, designated by the pre-defined mapper-identifier default, is as follows unless a user-defined mapper is specified for that type.

 
declare mapper(T v) map(tofrom: v)

Using the defaultmapper-identifier overrides the pre-defined default mapper for the given type, making it the default for all variables of type. All map clauses with this construct in scope that map a list item of type will use this mapper unless another is explicitly specified.

All map clauses on the directive are expanded into corresponding map clauses wherever this mapper is invoked, either by matching type or by being explicitly named in a map clause. A map clause with list item var maps var as though no mapper were specified.

The declare mapper directive can also appear at points in the program at which a static data member could be declared. In this case, the visibility and accessibility of the declaration are the same as those of a static data member declared at the same point in the program.

RestrictionsThe restrictions to the declare mapper directive are as follows:

No instance of type can be mapped as part of the mapper, either directly or indirectly through another type, except the instance passed as the list item. If a set of declare mapper directives results in a cyclic definition then the behavior is unspecified.
The type must be of struct, union or class type in C and C++ or a non-intrinsic type in Fortran.
The type must not declare a new type.
At least one map clause that maps var or at least one element of var is required.
List-items in map clauses on this construct may only refer to the declared variable var and entities that could be referenced by a procedure defined at the same location.
Each map-type-modifier can appear at most once on the map clause.
A mapper-identifier may not be redeclared in the current scope for the same type or for a type that is compatible according to the base language rules.

∙ type must not be an abstract type.

[next] [prev] [prev-tail] [front] [up]