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

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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 item1 is a list item in a map clause, and item2 is another list item in a map clause on the same construct that has a base pointer that is, or is part of, item1, then:

SVG-Viewer needed.

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.

SVG-Viewer needed.

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:

SVG-Viewer needed.

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.

SVG-Viewer needed.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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

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.

SVG-Viewer needed.

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:

SVG-Viewer needed.

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

SVG-Viewer needed.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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:

SVG-Viewer needed.

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;

SVG-Viewer needed.

SVG-Viewer needed.

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

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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:

SVG-Viewer needed.

SVG-Viewer needed.

Cross References

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  

SVG-Viewer needed.

and variable-category is one of:  

 
  scalar 
  aggregate 
  pointer  

SVG-Viewer needed.

SVG-Viewer needed.

and variable-category is one of:  

 
  scalar 
  aggregate 
  allocatable 
  pointer  

SVG-Viewer needed.

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

SVG-Viewer needed.

The syntax of the declare mapper directive is as follows:  

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

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the declare mapper directive is as follows:  

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

SVG-Viewer needed.

where:

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.

SVG-Viewer needed.

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.

SVG-Viewer needed.

RestrictionsThe restrictions to the declare mapper directive are as follows: