HOME
| OPENMP API Specification: Version 5.1 November 2020

2.21.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 attribute, map, is_device_ptr or has_device_addr 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 one of the data-sharing attribute, map, is_device_ptr or has_device_addr clauses.

2.21.7.1 map Clause

Summary The 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) 
present 
iterator(iterators-definition)  

Description The 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 map clause with a presentmap-type-modifier appears in a map clause, then the effect of the clause is ordered before all other map clauses that do not have the present modifier.

If the mappermap-type-modifier is not present, the behavior is as if the mapper(default) modifier was specified. The map behavior of a list item in a map clause is modified by a visible user-defined mapper (see Section 2.21.7.4) if the mapper has the same mapper-identifier as the mapper-identifier in the mapper map-type-modifier and is specified for a type that matches the type of the list item. The effect of the mapper is to remove the list item from the map clause, if the present modifier does not also appear, and to apply the clauses specified in the declared mapper to the construct on which the map clause appears. In the clauses applied by the mapper, references to var are replaced with references to the list item and the map-type is replaced with a final map type that is determined according to the rules of map-type decay (see Section 2.21.7.4).

A list item that is an array or array section of a type for which a user-defined mapper exists is mapped as if the map type decays to alloc, release, or delete, and then each array element is mapped with the original map type, as if by a separate construct, according to the mapper.

A list item in a map clause may reference iterators defined by an iterators-definition of an iterator modifier.

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

SVG-Viewer needed.

If a component of a derived type variable is a list item that results from the above rules for mapped structures and mapped structure elements, and it does not explicitly appear as another list item or as the base expression of another list item in a map clause on the construct, then:

SVG-Viewer needed.

Given item1 is a list item in a map clause, and item2 is another list item in a map clause on the same construct, if item2 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, a pointer variable is present in the device data environment that corresponds to the base pointer when the effect of the map clause occurs, and 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.
3.
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. They are guaranteed to share storage if the map clause appears on a target construct that corresponds to an inactive target region, or if it appears on a target data, target enter data, or target exit data construct that applies to the device data environment of the host device.

If a map clause appears on a target, target data, target enter data or target exit data construct with a presentmap-type-modifier then on entry to the region if the corresponding list item does not appear in the device data environment then an error occurs and the program terminates.

If a 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 they are 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 reference count of the corresponding list item was not already incremented because of the effect of a map clause on the construct then:
a)
The reference count is incremented by one;
3.
If the reference count of the corresponding list item 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 at the point 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 at the point 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 reference count of the corresponding list item is finite and was not already decremented because of the effect of a map clause on the construct then:
a)
The reference count of the corresponding list item is decremented by one;
2.
If the map-type is delete and the reference count of the corresponding list item is finite then:
a)
The reference count of the corresponding list item is set to zero;
3.
If the map-type is from or tofrom and if the reference count of the corresponding list item 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 at the point 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 original list item, if associated, will be associated with the same pointer target with which it was associated at the point 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 reference count of the corresponding list item 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 an original list item that has the ALLOCATABLE attribute is changed while a corresponding list item is present in the device data environment, the allocation status of the corresponding list item is unspecified until the list item is again mapped with an always modifier 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 Events The target-map event occurs when a thread maps data to or from a target device.

The target-data-op-begin event occurs before a thread initiates a data operation on a target device.

The target-data-op-end event occurs after a thread initiates a data operation on a target device.

Tool Callbacks A thread dispatches a registered ompt_callback_target_map or ompt_callback_target_map_emi 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 or ompt_callback_target_map_emi_t, respectively.

A thread dispatches a registered ompt_callback_target_data_op_emi callback with ompt_scope_begin as its endpoint argument for each occurrence of a target-data-op-begin event in that thread. Similarly, a thread dispatches a registered ompt_callback_target_data_op_emi callback with ompt_scope_end as its endpoint argument for each occurrence of a target-data-op-end event in that thread. These callbacks have type signature ompt_callback_target_data_op_emi_t.

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

Restrictions Restrictions to the map clause are as follows:

SVG-Viewer needed.

SVG-Viewer needed.

Cross References

SVG-Viewer needed.

2.21.7.2 Pointer Initialization for Device Data Environments

This section describes how a pointer that is predetermined firstprivate for a target construct may be assigned an initial value that is the address of an object that exists in a device data environment and corresponds to a matching mapped list item.

All previously mapped list items that have corresponding storage in a given device data environment constitute the set of currently mapped list items. If a currently mapped list item has a base pointer, the base address of the currently mapped list item is the value of its base pointer. Otherwise, the base address is determined by the following steps:

1.
Let X refer to the currently mapped list item.
2.
If X refers to an array section or array element, let X refer to its base array.
3.
If X refers to a structure element, let X refer to its containing structure and return to step 2.
4.
The base address for the currently mapped list item is the address of X.

Additionally, each currently mapped list item has a starting address and an ending address. The starting address is the address of the first storage location associated with the list item, and the ending address is the address of the storage location that immediately follows the last storage location associated with the list item.

The mapped address range of the currently mapped list item is the range of addresses that starts from the starting address and ends with the ending address. The extended address range of the currently mapped list item is the range of addresses that starts from the minimum of the starting address and the base address and that ends with the maximum of the ending address and the base address.

If the value of a given pointer is in the mapped address range of a currently mapped list item then that currently mapped list item is a matching mapped list item. Otherwise, if the value of the pointer is in the extended address range of a currently mapped list item then that currently mapped list item is a matching mapped list item.

If multiple matching mapped list items are found and they all appear as part of the same containing structure, the one that has the lowest starting address is treated as the sole matching mapped list item. Otherwise, if multiple matching mapped list items are found then the behavior is unspecified.

If a matching mapped list item is found, the initial value that is assigned to the pointer is a device address such that the corresponding list item in the device data environment can be accessed through the pointer in a target region.

If a matching mapped list item is not found, the assigned initial value of the pointer is NULL unless otherwise specified (see Section 2.5.1).

Cross References

SVG-Viewer needed.

2.21.7.3 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.21.7).

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 
  present  

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.

Description The 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), an is_device_ptr clause or a has_device_addr clause. If implicit-behavior is default, then the clause has no effect for the variables in the category specified by variable-category. If implicit-behavior is present, each variable referenced in the construct in the category specified by variable-category is treated as if it had been listed in a map clause with the map-type of alloc and map-type-modifier of present.

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

Description User-defined mappers can be defined using the declare mapper directive. The type and an optional mapper-identifier uniquely identify the mapper for use in a map clause or motion clause later in the program. The visibility and accessibility of this declaration are the same as those of a variable declared at the same location in the program.

If mapper-identifier is not specified, the behavior is as if mapper-identifier is default.

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 predefined mapper-identifier default, is defined as if by the following directive, unless a user-defined mapper is specified for that type.

SVG-Viewer needed.

 

 
#pragma omp declare mapper(T v) map(tofrom: v)  

SVG-Viewer needed.

SVG-Viewer needed.

 

 
!$omp declare mapper(T :: v) map(tofrom: v)  

SVG-Viewer needed.

A declare mapper directive that uses the defaultmapper-identifier overrides the predefined default mapper for the given type, making it the default mapper for variables of that type.

The effect that a user-defined mapper has on either a map clause that maps a list item of the given type or a motion clause that invokes the mapper and updates a list item of the given type is to replace the map or update with a set of map clauses or updates derived from the map clauses specified by the mapper, as described in Section 2.21.7.1 and Section 2.14.6.

The final map types that a mapper applies for a map clause that maps a list item of the given type are determined according to the rules of map-type decay, defined according to Table 2.13. Table 2.13 shows the final map type that is determined by the combination of two map types, where the rows represent the map type specified by the mapper and the columns represent the map type specified by a map clause that invokes the mapper. For a target exit data construct that invokes a mapper with a map clause that has the from map type, if a map clause in the mapper specifies an alloc or to map type then the result is a release map type.

A list item in a map clause that appears on a declare mapper directive may include array sections.


Table 2.13: Map-Type Decay of Map Type Combinations
alloc to from tofrom release delete







alloc alloc alloc alloc (release) alloc release delete
to alloc to alloc (release) to release delete
from alloc alloc from from release delete
tofrom alloc to from tofrom release delete

All map clauses that are introduced by a mapper are further subject to mappers that are in scope, except a map clause with list item var maps var without invoking a mapper.

SVG-Viewer needed.

The declare mapper directive can also appear at locations 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 location in the program.

SVG-Viewer needed.

Restrictions Restrictions to the declare mapper directive are as follows:

SVG-Viewer needed.

SVG-Viewer needed.

SVG-Viewer needed.

SVG-Viewer needed.

SVG-Viewer needed.

SVG-Viewer needed.

Cross References