\section{ \code{declare mapper} Construct}

\label{sec:declare_mapper}

The following examples show how to use the \code{declare mapper}

directive to prescribe a map for later use.

It is also quite useful for pre-defining partitioned and nested

structure elements.

In the first example the \code{declare mapper} directive specifies

that any structure of type \plc{myvec\_t} for which implicit data-mapping

rules apply will be mapped according to its \code{map} clause.

The variable \plc{v} is used for referencing the structure and its

elements within the \code{map} clause.

Within the \code{map} clause the \plc{v} variable specifies that all

elements of the structure are to be mapped. Additionally, the

array section \plc{v.data[0:v.len]} specifies that the dynamic

storage for data is to be mapped.

Within the main program the \plc{s} variable is typed as \plc{myvec\_t}.

Since the variable is found within the target region and the type has a mapping prescribed by

a \code{declare mapper} directive, it will be automatically mapped according to its prescription:

full structure, plus the dynamic storage of the \plc{data} element.

\cexample[5.0]{target_mapper}{1}

\ffreeexample[5.0]{target_mapper}{1}

The next example illustrates the use of the \plc{mapper-identifier} and deep copy within a structure.

The structure, \plc{dzmat\_t}, represents a complex matrix,

with separate real (\plc{r\_m}) and imaginary (\plc{i\_m}) elements.

Two map identifiers are created for partitioning the \plc{dzmat\_t} structure.

For the C/C++ code the first identifier is named \plc{top\_id} and maps the top half of

two matrices of type \plc{dzmat\_t}; while the second identifier, \plc{bottom\_id},

maps the lower half of two matrices.

Each identifier is applied to a different \code{target} construct,

as \code{map(mapper(top\_id), tofrom: a,b)}

and \code{map(mapper(bottom\_id), tofrom: a,b)}.

Each target offload is allowed to execute concurrently on two different devices

(\plc{0} and \plc{1}) through the \code{nowait} clause.

The OpenMP 5.0 \code{parallel master} construct creates a region of two threads

for these \code{target} constructs, with a single thread (\plc{master}) generator.

The Fortran code uses the \plc{left\_id} and \plc{right\_id} map identifiers in the

\code{map(mapper(left\_id),tofrom: a,b)} and \code{map(mapper(right\_id),tofrom: a,b)} map clauses.

The array sections for these left and right contiguous portions of the matrices

were defined previously in the \code{declare mapper} directive.

Note, the \plc{is} and \plc{ie} scalars are firstprivate

by default for a target region, but are declared firstprivate anyway

to remind the user of important firstprivate data-sharing properties required here.

\cexample[5.0]{target_mapper}{2}

\ffreeexample[5.0]{target_mapper}{2}

In the third example \plc{myvec} structures are

nested within a \plc{mypoints} structure. The \plc{myvec\_t} type is mapped

as in the first example. Following the \plc{mypoints} structure declaration,

the \plc{mypoints\_t} type is mapped by a \code{declare mapper} directive.

For this structure the \plc{hostonly\_data} element will not be mapped;

also the array section of \plc{x} (\plc{v.x[:1]}) and \plc{x} will be mapped; and

\plc{scratch} will be allocated and used as scratch storage on the device.

The default map-type mapping, \code{tofrom}, applies to the \plc{x} array section,

but not to \plc{scratch} which is explicitly mapped with the \code{alloc} map-type.

Note: the variable \plc{v} is not included in the map list (otherwise

the \plc{hostonly\_data} would be mapped)-- just the elements

to be mapped are listed.

The two mappers are combined when a \plc{mypoints\_t} structure type is mapped,

because the mapper \plc{myvec\_t} structure type is used within a \plc{mypoints\_t}

type structure.

\cexample[5.0]{target_mapper}{3}

\ffreeexample[5.0]{target_mapper}{3}