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.

• If a variable appears in a to or link clause on a declare target directive that does not have a device_type(nohost) clause 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 type pointer or reference to pointer, it is also treated as if it had 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, but not a function pointer or (for C++) a pointer to a member function, is treated as if it is the base pointer of a zero-length array section that had appeared as a list item in a map clause.

  ∙ A variable that is of type reference to pointer, but not a function pointer or a reference to a pointer to a member function 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 had 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 firstprivate (see Section 2.21.1.1).

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:

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

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

• If the construct is 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 construct is 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 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:

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.

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:

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

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.

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

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

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

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.

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.

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:

• Each of the map-type-modifier modifiers can appear at most once in 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 an expression that is used to form a list item in a map clause contains an iterator identifier, the list item instances that would result from different values of the iterator must not have the same containing array and must not have base pointers that share original 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 an array appears as a list item in a map clause, multiple parts of the array have corresponding storage in the device data environment prior to a task encountering the construct associated with the map clause, and the corresponding storage for those parts was created by maps from more than one earlier construct, the behavior is unspecified.
• 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 mappermap-type-modifier appears in a map clause, the type on which the specified mapper operates must match the type of the list items in the 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 a 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 of 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.

Cross References

• Array sections, see Section 2.1.5.
• Iterators, see Section 2.1.6.
• declare mapper directive, see Section 2.21.7.4.
• ompt_callback_target_data_op_t or ompt_callback_target_data_op_emi_t callback type, see Section 4.5.2.25.
• ompt_callback_target_map_t or ompt_callback_target_map_emi_t callback type, see Section 4.5.2.27.

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
       

 
  scalar 
  aggregate 
  pointer
       

 
  scalar 
  aggregate 
  allocatable 
  pointer
       

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

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

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

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

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.

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

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

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.

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.

Restrictions 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 var that is 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 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 the declare mapper directive 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.
• Multiple declare mapper directives that specify the same mapper-identifier for the same type or for compatible types, according to the base language rules, may not appear in the same scope.

Cross References

• target update construct, see Section 2.14.6.
• map clause, see Section 2.21.7.1.