Subject: hpff-doc: mapping-subr.tex

From: [email-masked] (Carl Offner)
Date: Fri, 18 Oct 1996 13:22:13 -0500 (CDT)

---------------------------------------------------------------------------
[email-masked] is a mailing list for HPF 2.0 language specification
authors and editors.  Instructions for adding or deleting yourself from this
list appear at the bottom of this message.
---------------------------------------------------------------------------
Some changes based on suggestions from Carol Munroe:

% File: mapping-subr.tex

% Contents:
% Mapping constructs for dummy arguments for HPF 2.0 document,
% including
%       interface rules
%       INHERIT
%
% If you don't have LaTeX2e available, uncomment the next three lines:
%\def\emph#1{{\em #1}}
%\def\texttt#1{{\tt #1}}
%\def\textit#1{{\it #1}}

% Revision history:
% Oct-18-96     Edit by Carl Offner, Digital.  Made some
%               clarifications based on suggestions from Carol
%               Munroe.  The only substantive change was a change in
%               the beginning of item 2 in the definition of
%               ``specialization'':  In this case, S cannot now have
%               the INHERIT attribute.  This was probably the
%               understood intent in any case; I don't believe it
%               restricts the definition in any essential way.
%
% Sep-26-96     Edit by Carl Offner, Digital.  Added section defining
%               the partial order on mappings.  Specified that
%               descriptive syntax is the same as prescriptive syntax
%               together with a (weak) assertion by the programmer
%               that no remapping is necessary.
%
% Sep-04-96     Edit by Carl Offner, Digital.  Added forward reference
%               to some approved extensions that allow subroutines to
%               permanently modify data.  Also added new subsection
%               making it clear that explicit mapping directives are
%               characteristics of dummy arguments and function
%               results.

% Aug-13-96     Edit by Carl Offner, Digital.  Some clarifications and
%               corrections of typos, based on suggestions from Rob
%               Schreiber.
%
% Aug-01-96     Edit by Carl Offner, Digital.  Based on
%               decisions taken at the July HPFF meeting,
%               i)  DISTRIBUTE is no longer allowed on INHERITed
%                   arguments.
%               ii) The section describing when an explicit interface
%                   is not needed when arguments are explicitly mapped
%                   has been vastly tightened up.
%               In addition, descriptive syntax has been more clearly
%               identified as being left in purely for backward
%               compatibility; and the TERPSICHORE-FRUG example has
%               been reworked.
%
% Jun-03-96     Edit by Carl Offner, Digital.
%               Rearrangements, many edits, and two new sections (an
%               introduction and the section on when an explicit
%               interface is necessary).
%
% May-10-96     Created by Charles Koelbel, Rice University
%               (from HPF 1.2 document and HPF 2.0 proposals)

\chapter{Data Mapping in Subprogram Interfaces}
\label{ch-mapping-subr}

\emph{In this section, phrases such as ``the caller must pass\dots''
  are constraints on the implementation (i.e., on the generated code
  produced by the compiler), not on the source code produced by the
  programmer.}

\section{Introduction}
\label{mapsub:introduction}

\emph{This introduction gives an overview of the ways in which mapping
directives interact with argument passing to subprograms.  The
language used here, however, is not definitive; the subsequent
subsections of this section contain the authoritative rules.}

In addition to the data mapping features described in
Section~\ref{ch-mapping-base}, HPF allows a number of options for
describing the mapping of dummy arguments.

The mapping of each such dummy argument may be related to the mapping
of its associated actual argument in the calling main program or
procedure (the ``caller'') in several different ways.  To allow for
this, mapping directives applied to dummy arguments can have three
different syntactic forms: \emph{prescriptive}, \emph{descriptive},
and \emph{transcriptive}.

HPF provides these three forms to allow the programmer either to
specify that the data is to be left in place, or to specify that
during the execution of the call the data must be automatically
remapped into a new and presumably more efficient mapping for the
duration of the execution of the called subprogram.

The meaning of these forms is as follows:

\begin{description}

\item[prescriptive] The directive describes the mapping of the dummy
  argument.  However, the actual argument need not have this mapping.
  \emph{If it does not}, it is the responsibility of the compiler to
  generate code to remap the argument as specified, and to restore the
  original mapping on exit.  This code may be generated in either the
  caller or in the called subprogram; the requirements for explicit
  interfaces in section~\ref{mapsub:ExplicitInterfaces} insure that
  the necessary information will be available at compile-time to
  perform the mapping in either place.

  Prescriptive directives are syntactically identical to directives
  occurring elsewhere in the program.  For instance, if \texttt{A} is
  a dummy argument,

                                                                \CODE
!HPF$ DISTRIBUTE A (BLOCK, CYCLIC)
                                                                \EDOC
  is a prescriptive directive.

\item[descriptive] Descriptive syntax has exactly the same meaning as
  prescriptive syntax, except that in addition it amounts to a weak
  assertion by the programmer that the actual argument requires no
  remapping.

  The assertion is characterized as ``weak'' because if it is false,
  the program is still standard-conforming.  In such a case, the
  compiler must generate the appropriate remapping.

  If the compiler can prove that the assertion is false, or if the
  compiler cannot verify that it is true, it may issue a warning or
  informational diagnostic message.

  \begin{users}
    The purpose of descriptive, as opposed to prescriptive, directives
    is simply to provide a possible way for the compiler to report
    information to the programmer that may be useful in program
    development and debugging.

    Note that any diagnostic message thay may be produced as a result
    of the use of descriptive directives is not a portable feature of
    this language.  In particular, there are instances in which no
    remapping is needed but where this fact would be impossible or
    highly non-trivial for a compiler to ascertain.  Different
    compilers may well emit messages in different circumstances; and
    there is no requirement that any such messages be emitted at all.
  \end{users}

  Descriptive directives look like prescriptive directives, except
  that an asterisk precedes the description.  For instance,
                                                                \CODE
!HPF$ DISTRIBUTE A *(BLOCK, CYCLIC)
                                                                \EDOC
  is a descriptive directive.

\item[transcriptive] The mapping is unspecified.  The called
  subprogram must accept the mapping of the argument as it is passed.
  (Of course this means that the caller must pass this mapping
  information at run-time.)

  Transcriptive directives are written with a single asterisk for
  distributions and processor arrays; for instance
                                                                \CODE
!HPF$ DISTRIBUTE A *
                                                                \EDOC
  is a transcriptive directive.  The \texttt{INHERIT} directive
  (see section~\ref{INHERIT-SECTION}) is used to specify a transcriptive
  alignment.

\end{description}

Both distribution formats and processor arrangements can be specified
prescriptively, descriptively, or transcriptively.  Alignment is more
complicated, because of the need to specify the template with which
the dummy is aligned.  This template may be unspecified (in this case
of course there is no \texttt{ALIGN} directive), in which case it is
the \emph{natural template} of the dummy.  (``Natural template'' is
defined in section~\ref{mapsub:templates} below.)  Otherwise, one of
the following disjoint possibilities must be true:

\begin{itemize}

\item The template is explicitly specified by a prescriptive
  \texttt{ALIGN} directive.

\item The template is explicitly specified by a descriptive
  \texttt{ALIGN} directive.

\item The template is \emph{inherited}.  This is specified by giving
  the dummy the \texttt{INHERIT} attribute (described in
  section~\ref{INHERIT-SECTION} below).  This implicitly specifies the
  template to be a copy of the template with which the corresponding
  actual argument is ultimately aligned; further, the alignment of the
  dummy with that template is the same as that of the corresponding
  actual.  This is in effect a transcriptive form of alignment.

\end{itemize}

This is restated more precisely in section~\ref{mapsub:templates}
below.

\begin{users}
  Although it is possible to write some combinations of mapping
  directives that are partially prescriptive and partially
  transcriptive, for instance, there is probably no virtue to so
  doing.  The point of these directives is to enable the compiler to
  handle any necessary remapping correctly and efficiently.  Now
  remapping can happen for one or more of the following reasons:

  \begin{itemize}
  \item  to make the alignment of the actual and the dummy agree;
  \item  to make the distribution of the actual and the dummy agree;
  \item  to make the processor array of the actual and the dummy agree.
  \end{itemize}

  For most machines, there is no real difference in the cost of
  remapping for any of these reasons.  It is therefore a better
  practice (for readability, at least) to make a mapping either purely
  transcriptive, purely prescriptive, or purely descriptive.

  While transcriptive mappings can be useful in writing libraries,
  they impose a run-time cost on the subprogram.  They should
  therefore be avoided in normal user code.
\end{users}

\section{What Remapping is Required, and Who Does It}

If there is an explicit interface for the called subprogram and that
interface contains prescriptive or descriptive mapping directives for
a dummy argument, and if a remapping of the corresponding actual
argument is necessary, the call should proceed as if the data was
copied to a temporary variable to match the mapping of the dummy
argument as expressed by the directives in the explicit interface.
The template of the dummy will then be as declared in the interface.

If there is no explicit interface, then no remapping will be
necessary; this is a consequence of the requirements in
section~\ref{mapsub:ExplicitInterfaces}.

An overriding principle is that \emph{any remapping of arguments is
not visible to the caller}.  That is, when the subprogram returns and
the caller resumes execution, all objects accessible to the caller
after the call are mapped exactly as they were before the call.  It is
not possible for a procedure to change the mapping of any object in a
manner visible to its caller.

\begin{users}
Some Approved Extensions relax this restriction; see for instance
sections~\ref{DYNAMIC-DUMMY-SECTION} and \ref{POINTERS-SECTION}.
\end{users}

\section{Distributions and Processor Arrangements}
\label{mapsub:DistProcArr}

In a \texttt{DISTRIBUTE} directive where every \textit{distributee} is
a dummy argument, either the \textit{dist-format-clause} or the
\textit{dist-target}, or both, may begin with, or consist of, an
asterisk.

\begin{itemize}

\item Without an asterisk, a \textit{dist-format-clause} or
  \textit{dist-target} is prescriptive; the clause describes a
  distribution and constitutes a request of the language processor to
  make it so.  This might entail either the caller or the called
  subprogram remapping or copying the actual argument on entry at run
  time in order to satisfy the requested distribution for the dummy.

\item Starting with an asterisk, a \textit{dist-format-clause} or
  \textit{dist-target} is descriptive.  Such a directive is equivalent
  in every respect to a prescriptive directive, except that if the
  compiler cannot verify that no remapping of the actual is required,
  it may issue a diagnostic message to that effect.  See
  section~\ref{mapsub:introduction} for further information on this
  point.

\item Consisting of only an asterisk, a \textit{dist-format-clause} or
  \textit{dist-target} is transcriptive; the clause says nothing about
  the distribution but constitutes a request of the language processor
  to copy that aspect of the distribution from that of the actual
  argument.  (The intent is that if the argument is passed by
  reference, no movement of the data will be necessary at run time.)
\end{itemize}

It is possible that, in a single \texttt{DISTRIBUTE} directive, the
\textit{dist-format-clause} might have an asterisk but not the
\textit{dist-target}, or vice versa.

\subsection{Examples}

These examples of \texttt{DISTRIBUTE} directives for dummy arguments
illustrate the various combinations:

                                                                        \CODE
!HPF$ DISTRIBUTE URANIA (CYCLIC) ONTO GALILEO
                                                                        \EDOC
The language processor should do whatever it takes to cause
\texttt{URANIA} to have a \texttt{CYCLIC} distribution on the
processor arrangement \texttt{GALILEO}.
                                                                        \CODE
!HPF$ DISTRIBUTE POLYHYMNIA * ONTO ELVIS
                                                                        \EDOC
The language processor should do whatever it takes to cause
\texttt{POLYHYMNIA} to be distributed onto the processor arrangement
\texttt{ELVIS}, using whatever distribution format it currently has
(which might be on some other processor arrangement).
                                                                        \CODE
!HPF$ DISTRIBUTE THALIA *(CYCLIC) ONTO *FLIP
                                                                        \EDOC
The language processor should do whatever it takes to cause
\texttt{THALIA} to have a \texttt{CYCLIC} distribution on the
processor arrangement \texttt{FLIP}; the programmer believes that the
actual is already distributed in this fashion and that no remapping is
required.
                                                                        \CODE
!HPF$ DISTRIBUTE EUTERPE (CYCLIC) ONTO *
                                                                        \EDOC
The language processor should do whatever it takes to cause
\texttt{EUTERPE} to have a \texttt{CYCLIC} distribution onto whatever
processor arrangement the actual was distributed onto.
                                                                        \CODE
!HPF$ DISTRIBUTE ERATO * ONTO *
                                                                        \EDOC
The mapping of \texttt{ERATO} should not be changed from that of the
actual argument.

Also note that \texttt{DISTRIBUTE ERATO * ONTO *} does not mean the
same thing as
                                                                        \CODE
!HPF$ DISTRIBUTE ERATO (*) ONTO *
                                                                        \EDOC
This latter means: distribute \texttt{ERATO} \texttt{*} (that is,
on-processor) onto whatever processor arrangement the actual was
distributed onto.  The processor arrangement is necessarily scalar in
this case.

\subsection{What Happens When a Clause is Omitted}

One may omit either the \textit{dist-format-clause} or the
\textit{dist-onto-clause} for a dummy argument.  This is understood as
follows:

If the dummy argument has the \texttt{INHERIT} attribute (see
section~\ref{INHERIT-SECTION}), then no distribution directive is
allowed in any case:  the distribution as well as the alignment is
inherited from the actual argument.

In any other case in which distribution information is omitted, the
compiler may choose the distribution format or a target processor
arrangement arbitrarily.

Here are two examples:
                                                                         \CODE
!HPF$ DISTRIBUTE WHEEL_OF_FORTUNE *(CYCLIC)
                                                                         \EDOC
The programmer believes that the actual argument corresponding to the
dummy argument \texttt{WHEEL_OF_FORTUNE} is already distributed
\texttt{CYCLIC}.  The compiler should insure that the mapping of the
passed data is in fact \texttt{CYCLIC}, and remap it if necessary if
it is not.  It may in addition be remapped onto some other processor
arrangement, but there is no reason to; most likely the programmer
would be surprised if such a remapping occurred.
                                                                          \CODE
!HPF$ DISTRIBUTE ONTO *TV :: DAVID_LETTERMAN
                                                                          \EDOC
The programmer believes that the actual argument corresponding to the
dummy argument \texttt{DAVID_LETTERMAN} is already distributed onto
\texttt{TV} in some fashion.  The compiler should insure that this is
so, and make it so if it is not.  The distribution format may be
changed as long as \texttt{DAVID_LETTERMAN} is kept on \texttt{TV}.
(Note that this declaration must be made in attributed form; the
statement form
                                                                        \CODE
!HPF$ DISTRIBUTE DAVID_LETTERMAN ONTO *TV         !Nonconforming
                                                                        \EDOC
does not conform to the syntax for a \texttt{DISTRIBUTE} directive.)

\section{Alignment}

\subsection{The Template of the Dummy Argument}
\label{mapsub:templates}

Here we describe precisely how to determine the template with which the dummy
argument is ultimately aligned:

First, templates are not passed through the subprogram argument
interface.  A dummy argument and its corresponding actual argument may
be aligned to the same template only if that template is accessible in
both the caller and the called subprogram either through host
association or use association.

In any other case, the template with which a dummy argument is aligned is
always distinct from the template with which the actual argument is
aligned, though it may be a copy (see section \ref{INHERIT-SECTION}).
On exit from a procedure, an HPF implementation arranges that the
actual argument is aligned with the same template with which it was
aligned before the call.

The template of the dummy argument is arrived at in one of three ways:

\begin{itemize}
\item If the dummy argument appears explicitly as an \textit{alignee}
  in an \texttt{ALIGN} directive, its template is the
  \textit{align-target} if the \textit{align-target} is a template;
  otherwise its template is the template with which the
  \textit{align-target} is ultimately aligned.

\item If the dummy argument is not explicitly aligned and does not
  have the \texttt{INHERIT} attribute (described in
  section~\ref{INHERIT-SECTION} below), then the template has the same
  shape and bounds as the dummy argument; this is called the
  \textit{natural template} for the dummy.

  (Thus, all the examples in section~\ref{mapsub:DistProcArr} use
  the natural template.)

\item If the dummy argument is not explicitly aligned and does have
  the \texttt{INHERIT} attribute, then the template is ``inherited'' from
  the actual argument according to the following rules:

  \begin{itemize}

  \item If the actual argument is a whole array, the template of the
    dummy is a copy of the template with which the actual argument is
    ultimately aligned.

  \item If the actual argument is an array section of array \(A\)
    where no subscript is a vector subscript, then the template of the
    dummy is a copy of the template with which \(A\) is ultimately
    aligned.

  \item If the actual argument is any other expression, the shape
    and distribution of the template may be chosen arbitrarily by
    the language processor (and therefore the programmer cannot know
    anything \textit{a priori} about its distribution).

  \end{itemize}

  In all of these cases, we say that the dummy has an \textit{inherited
  template}.

\end{itemize}

\subsection{The INHERIT Directive}
\label{INHERIT-SECTION}

The \texttt{INHERIT} directive specifies that a dummy argument should be
aligned to a copy of the template of the corresponding actual argument
in the same way that the actual argument is aligned.

                                                                        \BNF
inherit-directive      \IS  INHERIT inheritee-list

inheritee               \IS object-name
                                                                        \FNB

\begin{constraints}

\item An \textit{inheritee} must be a dummy argument.
\item An \textit{inheritee} must not be an \textit{alignee}.
\item An \textit{inheritee} must not be a \textit{distributee}.

\end{constraints}

\begin{users}
The first of these three constraints is relaxed for pointers under the
approved extensions (see section~\ref{POINTERS-SECTION}).
\end{users}

The \texttt{INHERIT} directive causes the named subprogram dummy
arguments to have the \texttt{INHERIT} attribute.  Only dummy
arguments may have the \texttt{INHERIT} attribute.  An object must not
have both the \texttt{INHERIT} attribute and the \texttt{ALIGN}
attribute.  The \texttt{INHERIT} directive may appear only in a
\textit{specification-part} of a scoping unit.

If a dummy argument has the \texttt{TARGET} attribute and no explicit
mapping attributes, then the \texttt{INHERIT} attribute is implicitly
assumed.  (See section~\ref{mapsub:pointers}.)

The \texttt{INHERIT} attribute specifies that the template for a dummy
argument should be inherited, by making a copy of the template of the
actual argument.  Moreover, no other explicit mapping directive may
appear for an argument with the \texttt{INHERIT} attribute: the
\texttt{INHERIT} attribute implies a distribution of
\texttt{DISTRIBUTE~*~ONTO~*} for the inherited template.  Thus, the
net effect is to tell the compiler to leave the data exactly where it
is, and not attempt to remap the actual argument.  The dummy argument
will be mapped in exactly the same manner as the actual argument; the
subprogram must be compiled in such a way as to work correctly no
matter how the actual argument may be mapped onto abstract processors.

Note that if \texttt{A} is an array dummy argument, the directive
                                                                        \CODE
!HPF$ INHERIT A
                                                                        \EDOC
is more general than
                                                                        \CODE
!HPF$ DISTRIBUTE A * ONTO *
                                                                        \EDOC
for the following reason: The \texttt{INHERIT} directive states that
the (inherited) template with which \texttt{A} is aligned is
distributed \texttt{* ONTO *}, but that \texttt{A} may be aligned in
some non-trivial manner with that template. On the other hand, the
\texttt{DISTRIBUTE} directive states that \texttt{A} is aligned
trivially with its natural template, which in turn is distributed
\texttt{* ONTO *}.

For example, the following code is not permitted:
                                                                        \CODE
!HPF$ PROCESSORS P(2)
      REAL, DIMENSION(100) :: A
!HPF$ DISTRIBUTE (BLOCK) ONTO P :: A

      CALL FOO(A(1:50))

      ...

      SUBROUTINE FOO(D)
      REAL, DIMENSION(50) :: D
!HPF$ DISTRIBUTE D *            ! Illegal
                                                                        \EDOC
The transcriptive distribution for \texttt{D} is illegal because the
natural template for \texttt{D} is not distributed \texttt{BLOCK}.  On
the other hand, it would be legitimate to replace the illegal
directive by
                                                                        \CODE
!HPF$ INHERIT D
                                                                        \EDOC

\subsubsection{Examples}

Here is a straightforward example of the use of \texttt{INHERIT}:

                                            \CODE

      REAL DOUGH(100)
!HPF$ DISTRIBUTE DOUGH(BLOCK(10))
      CALL PROBATE( DOUGH(7:23:2) )
      ...
      SUBROUTINE PROBATE(BREAD)
      REAL BREAD(9)
!HPF$ INHERIT BREAD
                                             \EDOC

The inherited template of \texttt{BREAD} has shape [100]; element
\texttt{BREAD(I)} is aligned with element 5 + 2*I of the inherited
template, and that template has a \texttt{BLOCK(10)} distribution.

More complicated examples can easily be constructed.  It is important
to bear in mind that the inherited template may have a different rank
than the rank of the dummy, and it may even have a different rank than
the rank of the actual.  For instance, one might have a program
containing the following:

                                                \CODE
      REAL A(100,100)
!HPF$ TEMPLATE T(100,100,100)
!HPF$ DISTRIBUTE T(BLOCK,CYCLIC,*)
!HPF$ ALIGN A(I,J) with T(J,3,I)
      CALL SUBR(A(:,7))
      ...
      SUBROUTINE SUBR(D)
      REAL D(100)
!HPF$ INHERIT D
                                                 \EDOC

In this case, the dummy \texttt{D} has rank 1.  It corresponds to a
1-dimensional section of a 2-dimensional actual \texttt{A} which in
turn is aligned with a 2-dimensional section of a 3-dimensional
template \texttt{T}.  The template of \texttt{D} is a copy of this
three-dimensional template.  \texttt{D} is aligned with the section
\texttt{(7, 3, :)} of this inherited template.  Thus, the ``visible''
dimension of the dummy \texttt{D} is distributed \texttt{*}, although
if the call statement had been

                                                \CODE
      CALL SUBR(A(7,:))
                                                 \EDOC

\noindent
for instance, the ``visible'' dimension of the dummy would be
distributed \texttt{BLOCK}.

\subsection{ALIGN Directive}

The presence or absence of an asterisk at the start of an
\textit{align-spec} has the same meaning as in a
\textit{dist-format-clause}: it specifies whether the \texttt{ALIGN}
directive is descriptive or prescriptive, respectively.

If an \textit{align-spec} that does not begin with \texttt{*} is
applied to a dummy argument, the meaning is that the dummy argument
will be forced to have the specified alignment on entry to the
subprogram.  This may require either the caller or the subprogram to
temporarily remap the data of the actual argument or a copy thereof.

Note that a dummy argument may also be used as an \textit{align-target}.
                                                                        \CODE
      SUBROUTINE NICHOLAS(TSAR,CZAR)
      REAL, DIMENSION(1918) :: TSAR,CZAR
!HPF$ INHERIT :: TSAR
!HPF$ ALIGN WITH TSAR :: CZAR
                                                                        \EDOC

In this example the first dummy argument, \texttt{TSAR}, remains
aligned with the corresponding actual argument, while the second dummy
argument, \texttt{CZAR}, is forced to be aligned with the first dummy
argument.  If the two actual arguments are already aligned, no
remapping of the data will be required at run time.  If they are not,
some remapping will take place.

If the \textit{align-spec} begins with ``\texttt{*}'', then the
\textit{alignee} must be a dummy argument.  The ``\texttt{*}''
indicates that the programmer believes that the actual argument
already has the specified alignment, and that no action to remap it is
required at run time.  (As before, there is no requirement that the
programmer's belief is correct, and the compiler must generate a
remapping if one appears to be necessary, just as in the case of a
prescriptive alignment.)  For example, if in the above example the
alignment directive were changed to

                                                                        \CODE
!HPF$ ALIGN WITH *TSAR :: CZAR
                                                                        \EDOC
then the programmer is expressing a belief that no remapping of the
actual argument corresponding to TSAR will be necessary.

It is not permitted to say simply ``\texttt{ALIGN WITH *}''; an
\textit{align-target} must follow the asterisk.  (The proper way to
say ``accept any alignment'' is \texttt{INHERIT}.)

If a dummy argument has no explicit \texttt{ALIGN} or
\texttt{DISTRIBUTE} attribute, then the compiler provides an implicit
alignment and distribution specification, one that could have been
described explicitly without any ``assertion asterisks''.

\subsubsection{Example}

Without using \texttt{INHERIT}, explicit alignment of a dummy argument
may be necessary to insure that no remapping takes place at the
subprogram boundary.  Here is an example:

                                                                       \CODE
      LOGICAL FRUG(128)
!HPF$ PROCESSORS DANCE_FLOOR(16)
!HPF$ DISTRIBUTE (BLOCK) ONTO DANCE_FLOOR::FRUG
      CALL TERPSICHORE(FRUG(1:40:3))
                                                                        \EDOC

The array section \texttt{FRUG(1:40:3)} is mapped onto abstract
processors in the following manner:
\begin{center}
\setlength{\unitlength}{0.01in}
\begin{picture}(560,225)(0,0)
\put(0,200){\makebox(35,25){\small\rm 1}}
\put(35,200){\makebox(35,25){\small\rm 2}}
\put(70,200){\makebox(35,25){\small\rm 3}}
\put(105,200){\makebox(35,25){\small\rm 4}}
\put(140,200){\makebox(35,25){\small\rm 5}}
\put(175,200){\makebox(35,25){\small\rm 6}}
\put(210,200){\makebox(35,25){\small\rm 7}}
\put(245,200){\makebox(35,25){\small\rm 8}}
\put(280,200){\makebox(35,25){\small\rm 9}}
\put(315,200){\makebox(35,25){\small\rm 10}}
\put(350,200){\makebox(35,25){\small\rm 11}}
\put(385,200){\makebox(35,25){\small\rm 12}}
\put(420,200){\makebox(35,25){\small\rm 13}}
\put(455,200){\makebox(35,25){\small\rm 14}}
\put(490,200){\makebox(35,25){\small\rm 15}}
\put(525,200){\makebox(35,25){\small\rm 16}}
\thinlines
\multiput(0,25)(0,25){7}{\line(1,0){560}}
\thicklines
\multiput(0,0)(0,200){2}{\line(1,0){560}}
\multiput(0,0)(35,0){17}{\line(0,1){200}}
\put(0,175){\makebox(35,25){\tt 1}}
\put(0,100){\makebox(35,25){\tt 4}}
\put(0,25){\makebox(35,25){\tt 7}}
\put(35,150){\makebox(35,25){\tt 10}}
\put(35,75){\makebox(35,25){\tt 13}}
\put(35,0){\makebox(35,25){\tt 16}}
\put(70,125){\makebox(35,25){\tt 19}}
\put(70,50){\makebox(35,25){\tt 22}}
\put(105,175){\makebox(35,25){\tt 25}}
\put(105,100){\makebox(35,25){\tt 28}}
\put(105,25){\makebox(35,25){\tt 31}}
\put(140,150){\makebox(35,25){\tt 34}}
\put(140,75){\makebox(35,25){\tt 37}}
\put(140,0){\makebox(35,25){\tt 40}}
\end{picture}
\end{center}

Suppose first that the interface to the subroutine
\texttt{TERPSICHORE} looks like this:

                                                                        \CODE
      SUBROUTINE TERPSICHORE(FOXTROT)
      LOGICAL FOXTROT(:)
!HPF$ INHERIT FOXTROT
                                                                        \EDOC
The template of \texttt{FOXTROT} is a copy of the 128 element
template of the whole array \texttt{FRUG}.  The template is mapped like this:

\begin{center}
\setlength{\unitlength}{0.01in}
\begin{picture}(560,225)(0,0)
\put(0,200){\makebox(35,25){\small\rm 1}}
\put(35,200){\makebox(35,25){\small\rm 2}}
\put(70,200){\makebox(35,25){\small\rm 3}}
\put(105,200){\makebox(35,25){\small\rm 4}}
\put(140,200){\makebox(35,25){\small\rm 5}}
\put(175,200){\makebox(35,25){\small\rm 6}}
\put(210,200){\makebox(35,25){\small\rm 7}}
\put(245,200){\makebox(35,25){\small\rm 8}}
\put(280,200){\makebox(35,25){\small\rm 9}}
\put(315,200){\makebox(35,25){\small\rm 10}}
\put(350,200){\makebox(35,25){\small\rm 11}}
\put(385,200){\makebox(35,25){\small\rm 12}}
\put(420,200){\makebox(35,25){\small\rm 13}}
\put(455,200){\makebox(35,25){\small\rm 14}}
\put(490,200){\makebox(35,25){\small\rm 15}}
\put(525,200){\makebox(35,25){\small\rm 16}}
\thinlines
\multiput(0,25)(0,25){7}{\line(1,0){560}}
\thicklines
\multiput(0,0)(0,200){2}{\line(1,0){560}}
\multiput(0,0)(35,0){17}{\line(0,1){200}}
\put(0,175){\makebox(35,25){\tt 1}}
\put(0,150){\makebox(35,25){\tt 2}}
\put(0,125){\makebox(35,25){\tt 3}}
\put(0,100){\makebox(35,25){\tt 4}}
\put(0,75){\makebox(35,25){\tt 5}}
\put(0,50){\makebox(35,25){\tt 6}}
\put(0,25){\makebox(35,25){\tt 7}}
\put(0,0){\makebox(35,25){\tt 8}}
\put(35,175){\makebox(35,25){\tt 9}}
\put(35,150){\makebox(35,25){\tt 10}}
\put(35,125){\makebox(35,25){\tt 11}}
\put(35,100){\makebox(35,25){\tt 12}}
\put(35,75){\makebox(35,25){\tt 13}}
\put(35,50){\makebox(35,25){\tt 14}}
\put(35,25){\makebox(35,25){\tt 15}}
\put(35,0){\makebox(35,25){\tt 16}}
\put(70,175){\makebox(35,25){\tt 17}}
\put(70,150){\makebox(35,25){\tt 18}}
\put(70,125){\makebox(35,25){\tt 19}}
\put(70,100){\makebox(35,25){\tt 20}}
\put(70,75){\makebox(35,25){\tt 21}}
\put(70,50){\makebox(35,25){\tt 22}}
\put(70,25){\makebox(35,25){\tt 23}}
\put(70,0){\makebox(35,25){\tt 24}}
\put(105,175){\makebox(35,25){\tt 25}}
\put(105,150){\makebox(35,25){\tt 26}}
\put(105,125){\makebox(35,25){\tt 27}}
\put(105,100){\makebox(35,25){\tt 28}}
\put(105,75){\makebox(35,25){\tt 29}}
\put(105,50){\makebox(35,25){\tt 30}}
\put(105,25){\makebox(35,25){\tt 31}}
\put(105,0){\makebox(35,25){\tt 32}}
\put(140,175){\makebox(35,25){\tt 33}}
\put(140,150){\makebox(35,25){\tt 34}}
\put(140,125){\makebox(35,25){\tt 35}}
\put(140,100){\makebox(35,25){\tt 36}}
\put(140,75){\makebox(35,25){\tt 37}}
\put(140,50){\makebox(35,25){\tt 38}}
\put(140,25){\makebox(35,25){\tt 39}}
\put(140,0){\makebox(35,25){\tt 40}}
\put(175,175){\makebox(35,25){\tt 41}}
\put(175,150){\makebox(35,25){\tt 42}}
\put(175,125){\makebox(35,25){\tt 43}}
\put(175,100){\makebox(35,25){\tt 44}}
\put(175,75){\makebox(35,25){\tt 45}}
\put(175,50){\makebox(35,25){\tt 46}}
\put(175,25){\makebox(35,25){\tt 47}}
\put(175,0){\makebox(35,25){\tt 48}}
\put(210,175){\makebox(35,25){\tt 49}}
\put(210,150){\makebox(35,25){\tt 50}}
\put(210,125){\makebox(35,25){\tt 51}}
\put(210,100){\makebox(35,25){\tt 52}}
\put(210,75){\makebox(35,25){\tt 53}}
\put(210,50){\makebox(35,25){\tt 54}}
\put(210,25){\makebox(35,25){\tt 55}}
\put(210,0){\makebox(35,25){\tt 56}}
\put(245,175){\makebox(35,25){\tt 57}}
\put(245,150){\makebox(35,25){\tt 58}}
\put(245,125){\makebox(35,25){\tt 59}}
\put(245,100){\makebox(35,25){\tt 60}}
\put(245,75){\makebox(35,25){\tt 61}}
\put(245,50){\makebox(35,25){\tt 62}}
\put(245,25){\makebox(35,25){\tt 63}}
\put(245,0){\makebox(35,25){\tt 64}}
\put(280,175){\makebox(35,25){\tt 65}}
\put(280,150){\makebox(35,25){\tt 66}}
\put(280,125){\makebox(35,25){\tt 67}}
\put(280,100){\makebox(35,25){\tt 68}}
\put(280,75){\makebox(35,25){\tt 69}}
\put(280,50){\makebox(35,25){\tt 70}}
\put(280,25){\makebox(35,25){\tt 71}}
\put(280,0){\makebox(35,25){\tt 72}}
\put(315,175){\makebox(35,25){\tt 73}}
\put(315,150){\makebox(35,25){\tt 74}}
\put(315,125){\makebox(35,25){\tt 75}}
\put(315,100){\makebox(35,25){\tt 76}}
\put(315,75){\makebox(35,25){\tt 77}}
\put(315,50){\makebox(35,25){\tt 78}}
\put(315,25){\makebox(35,25){\tt 79}}
\put(315,0){\makebox(35,25){\tt 80}}
\put(350,175){\makebox(35,25){\tt 81}}
\put(350,150){\makebox(35,25){\tt 82}}
\put(350,125){\makebox(35,25){\tt 83}}
\put(350,100){\makebox(35,25){\tt 84}}
\put(350,75){\makebox(35,25){\tt 85}}
\put(350,50){\makebox(35,25){\tt 86}}
\put(350,25){\makebox(35,25){\tt 87}}
\put(350,0){\makebox(35,25){\tt 88}}
\put(385,175){\makebox(35,25){\tt 89}}
\put(385,150){\makebox(35,25){\tt 90}}
\put(385,125){\makebox(35,25){\tt 91}}
\put(385,100){\makebox(35,25){\tt 92}}
\put(385,75){\makebox(35,25){\tt 93}}
\put(385,50){\makebox(35,25){\tt 94}}
\put(385,25){\makebox(35,25){\tt 95}}
\put(385,0){\makebox(35,25){\tt 96}}
\put(420,175){\makebox(35,25){\tt 97}}
\put(420,150){\makebox(35,25){\tt 98}}
\put(420,125){\makebox(35,25){\tt 99}}
\put(420,100){\makebox(35,25){\tt 100}}
\put(420,75){\makebox(35,25){\tt 101}}
\put(420,50){\makebox(35,25){\tt 102}}
\put(420,25){\makebox(35,25){\tt 103}}
\put(420,0){\makebox(35,25){\tt 104}}
\put(455,175){\makebox(35,25){\tt 105}}
\put(455,150){\makebox(35,25){\tt 106}}
\put(455,125){\makebox(35,25){\tt 107}}
\put(455,100){\makebox(35,25){\tt 108}}
\put(455,75){\makebox(35,25){\tt 109}}
\put(455,50){\makebox(35,25){\tt 110}}
\put(455,25){\makebox(35,25){\tt 111}}
\put(455,0){\makebox(35,25){\tt 112}}
\put(490,175){\makebox(35,25){\tt 113}}
\put(490,150){\makebox(35,25){\tt 114}}
\put(490,125){\makebox(35,25){\tt 115}}
\put(490,100){\makebox(35,25){\tt 116}}
\put(490,75){\makebox(35,25){\tt 117}}
\put(490,50){\makebox(35,25){\tt 118}}
\put(490,25){\makebox(35,25){\tt 119}}
\put(490,0){\makebox(35,25){\tt 120}}
\put(525,175){\makebox(35,25){\tt 121}}
\put(525,150){\makebox(35,25){\tt 122}}
\put(525,125){\makebox(35,25){\tt 123}}
\put(525,100){\makebox(35,25){\tt 124}}
\put(525,75){\makebox(35,25){\tt 125}}
\put(525,50){\makebox(35,25){\tt 126}}
\put(525,25){\makebox(35,25){\tt 127}}
\put(525,0){\makebox(35,25){\tt 128}}
\end{picture}
\end{center}

\noindent
\texttt{FOXTROT(I)} is aligned with element 3*I-2 of the template.

Suppose on the other hand that the interface to \texttt{TERPSICHORE} looks
like this:

                                                                        \CODE
      SUBROUTINE TERPSICHORE(FOXTROT)
      LOGICAL FOXTROT(:)
!HPF$ DISTRIBUTE FOXTROT(BLOCK)
                                                                        \EDOC

In this case, the template of \texttt{FOXTROT} is its natural
template; it has the same size 14 as \texttt{FOXTROT} itself.  The
actual argument, \texttt{FRUG(1:40:3)} is mapped to the 16 processors
in this manner:

\begin{center}
\begin{tabular}{cc}
Abstract  &  Elements \\
processor & of FRUG \\
1 & 1, 2, 3 \\
2 & 4, 5, 6 \\
3 & 7, 8 \\
4 & 9, 10, 11 \\
5 & 12, 13, 14 \\
6--16   &  none
\end{tabular}
\end{center}

That is, the original positions (in the template of the actual
argument) of the elements of the dummy are as follows:

\begin{center}
\setlength{\unitlength}{0.01in}
\begin{picture}(560,225)(0,0)
\put(0,200){\makebox(35,25){\small\rm 1}}
\put(35,200){\makebox(35,25){\small\rm 2}}
\put(70,200){\makebox(35,25){\small\rm 3}}
\put(105,200){\makebox(35,25){\small\rm 4}}
\put(140,200){\makebox(35,25){\small\rm 5}}
\put(175,200){\makebox(35,25){\small\rm 6}}
\put(210,200){\makebox(35,25){\small\rm 7}}
\put(245,200){\makebox(35,25){\small\rm 8}}
\put(280,200){\makebox(35,25){\small\rm 9}}
\put(315,200){\makebox(35,25){\small\rm 10}}
\put(350,200){\makebox(35,25){\small\rm 11}}
\put(385,200){\makebox(35,25){\small\rm 12}}
\put(420,200){\makebox(35,25){\small\rm 13}}
\put(455,200){\makebox(35,25){\small\rm 14}}
\put(490,200){\makebox(35,25){\small\rm 15}}
\put(525,200){\makebox(35,25){\small\rm 16}}
\thinlines
\multiput(0,25)(0,25){7}{\line(1,0){560}}
\thicklines
\multiput(0,0)(0,200){2}{\line(1,0){560}}
\multiput(0,0)(35,0){17}{\line(0,1){200}}
\put(0,175){\makebox(35,25){\tt 1}}
\put(0,100){\makebox(35,25){\tt 2}}
\put(0,25){\makebox(35,25){\tt 3}}
\put(35,150){\makebox(35,25){\tt 4}}
\put(35,75){\makebox(35,25){\tt 5}}
\put(35,0){\makebox(35,25){\tt 6}}
\put(70,125){\makebox(35,25){\tt 7}}
\put(70,50){\makebox(35,25){\tt 8}}
\put(105,175){\makebox(35,25){\tt 9}}
\put(105,100){\makebox(35,25){\tt 10}}
\put(105,25){\makebox(35,25){\tt 11}}
\put(140,150){\makebox(35,25){\tt 12}}
\put(140,75){\makebox(35,25){\tt 13}}
\put(140,0){\makebox(35,25){\tt 14}}
\end{picture}
\end{center}

This layout (3 elements on the first processor, 3 on the second, 2 on
the third, 3 on the fourth, \dots) cannot properly be described as a
\texttt{BLOCK} distribution.  Therefore, remapping will take place at
the call.

Remapping can be avoided without using \texttt{INHERIT} by explicitly
aligning the dummy to a declared template of size 128 distributed
\texttt{BLOCK}:

                                                                        \CODE
      SUBROUTINE TERPSICHORE(FOXTROT)
      LOGICAL FOXTROT(:)
!HPF$ PROCESSORS DANCE_FLOOR(16)
!HPF$ TEMPLATE, DISTRIBUTE(BLOCK) ONTO DANCE_FLOOR::GURF(128)
!HPF$ ALIGN FOXTROT(J) WITH GURF(3*J-2)
                                                                        \EDOC

\begin{users}
  The advantage of this technique is that, where it can be used, it
  gives the compiler more information; this information can often be
  used to generate more efficient code.
\end{users}

\section{Equivalence and Partial Order on the Set of Mappings}
\label{mapsub:PartialOrderOnMaps}

The set of mappings of named objects is endowed with a partial order
modulo a certain equivalence.  Roughly speaking, if \(P\) and \(Q\)
are two mappings, then \(P\geq Q\) means that \(P\) is partially
specified, and that \(Q\) is one of the mappings that is consistent
with \(P\).  This notion is used below in
section~\ref{mapsub:ExplicitInterfaces}, and also in
section~\ref{POINTERS-SECTION}.

\begin{users}
  Since these conditions are complex to state, it is worth noting that
  if you always provide explicit interfaces (which, as explained
  below, is quite easy and generally happens automatically), and if
  you don't use mapped pointers (an Approved Extension, explained
  below in section~\ref{POINTERS-SECTION}), then you can completely
  omit reading this section.
\end{users}

The precise definition is as follows.

First, we define a notion of equivalence for \textit{dist-format}
specifications:

\begin{enumerate}
\item Each \textit{dist-format} is equivalent to itself.

\item  Using the notation \(\equiv\) for the phrase ``is equivalent to'',

  \[\begin{array}{rclcl}
    \texttt{BLOCK}(n)  &\equiv& \texttt{BLOCK}(m) & \mbox{iff } m
    \mbox{ and } n \mbox{ have the same value} \\
    \texttt{CYCLIC}(n) &\equiv& \texttt{CYCLIC}(m) & \mbox{iff } m
    \mbox{ and } n \mbox{ have the same value} \\
    \texttt{CYCLIC}    &\equiv& \texttt{CYCLIC}(1) \\
  \end{array}\]

\item Other than this, no two lexically distinct \textit{dist-format}
  specifications are equivalent.
\end{enumerate}

Equivalence, thus defined, is an equivalence relation in the usual sense.

Now the partial order on mappings is defined: Let \texttt{S} (``special'')
and \texttt{G} (``general'') be two data objects.

The mapping of \texttt{S} is a \emph{specialization} of the mapping of
\texttt{G} if and only if either:

\begin{enumerate}

\item \texttt{G} has the \texttt{INHERIT} attribute, or

\item \texttt{S} does not have the \texttt{INHERIT} attribute, and the
  following constraints all hold:

  \begin{enumerate}
  \item \texttt{S} is a named object, and
  \item The shapes of the ultimate align targets of \texttt{S} and \texttt{G}
    are the same, and
  \item The dimensions of \texttt{S} and \texttt{G} each correspond to the same
    dimension of their respective ultimate align targets, and
    corresponding elements of \texttt{S} and \texttt{G} are aligned with the
    same corresponding elements of their respective ultimate align
    targets, and
  \item Either

    \begin{enumerate}
    \item The ultimate align targets of \texttt{S} and \texttt{G} are not
      explicitly distributed, or
    \item Both ultimate align targets of \texttt{S} and \texttt{G} are
      explicitly distributed.  In this case, the distribution
      directive specified for the ultimate align target of \texttt{G} must
      satisfy one of the following conditions:

      \begin{enumerate}
      \item It must have no \textit{dist-onto-clause}, or
      \item It must have a \textit{dist-onto-clause} of
        ``\texttt{ONTO} *'', or
      \item It must have a \textit{dist-onto-clause} specifying a
        processor arrangement having the same shape as that
        explicitly specified in a distribution directive for the
        ultimate align target of \texttt{S}.
      \end{enumerate}

      and the distribution directive for the ultimate align target of
      \texttt{G} must also satisfy one of the following conditions:

      \begin{enumerate}
      \item It must have no \textit{dist-format-clause}, or
      \item It must have a \textit{dist-format-clause} of ``*'', or
      \item Each \textit{dist-format} must be equivalent (in the sense
        defined above) to the \textit{dist-format} in the
        corresponding position of the \textit{dist-format-clause} in
        an explicit distribution directive for the ultimate align
        target of \texttt{S}.
      \end{enumerate}

    \end{enumerate}

  \end{enumerate}

\end{enumerate}

With this definition,

\begin{itemize}
\item Any mapping of a named object is a specialization of itself.
\item If \(A\), \(B\), and \(C\) are named objects, and if the mapping
  of \(A\) is a specialization of the mapping of \(B\) and the mapping
  of \(B\) is a specialization of the mapping of \(C\), then the
  mapping of \(A\) is a specialization of the mapping of \(C\).
\end{itemize}

That is, the specialization relation, as applied to mappings of named
objects, is reflexive and transitive, and it can therefore be applied
to produce an equivalence relation on the set of mappings of named
objects: two such mappings can be said to be equivalent iff each is a
specialization of the other.  With this definition, the specialization
relation yields a partial ordering on the set of mappings of named
objects, modulo equivalence.  The \texttt{INHERIT} mapping is the
unique maximal element in this partial order.

\section{Explicit Interfaces}
\label{mapsub:ExplicitInterfaces}

Under certain conditions, an explicit interface for a subprogram is
not required.  The conditions in Fortran under which this is allowable
are tightened considerably for HPF programs that use mapping
directives.

\begin{users}
  These conditions are complex.  The important thing to realize is
  that you don't have to read any of this if you have an explicit
  interface.  So if there is any doubt in your mind, just make sure
  you have an explicit interface.
\end{users}

An explicit interface is required \emph{except} when all of the
following conditions hold:

\begin{enumerate}

\item  Fortran does not require one, \emph{and}

\item No dummy argument is distributed transcriptively or with the
  \texttt{INHERIT} attribute, \emph{and}

\item For each pair of corresponding actual and dummy arguments, either:

  \begin{enumerate}

  \item They are both implicitly mapped, or

  \item They are both explicitly mapped and

    \begin{enumerate}
    \item The mapping of the actual argument is a specialization of
      the mapping of the dummy argument, and
    \item If the ultimate align targets of the actual and dummy
      arguments are both explicitly distributed, then the
      \textit{dist-onto-clause} of each must specify processor
      arrangements with the same shape.
    \end{enumerate}

  \end{enumerate}

  \emph{and}

\item For each pair of corresponding actual and dummy arguments, either:

  \begin{enumerate}

  \item Both are sequential, or

  \item Both are nonsequential.

  \end{enumerate}

\end{enumerate}

\begin{rationale}
  This has the following consequences:

  \begin{itemize}

  \item A plain Fortran program (i.e., with no HPF directives) will
    continue to be legal without the need to add additional
    interfaces, at least in a compilation environment in which all
    variables are sequential by default.  This is insured by items 1,
    2, 3a, and 4a. 

  \item If remapping is necessary, this fact will be visible to the
    caller.  Thus the implementation may choose to have all remapping
    performed by the caller.

  \end{itemize}
\end{rationale}

\begin{users}
  This requirement pushes the user strongly in the direction of always
  providing explicit interfaces.  This is a good thing---explicit
  interfaces allow many errors to be caught at compile-time and greatly
  speed up the process of robust software development.

  Note, that an explicit interface can be provided in three ways:

  \begin{enumerate}

  \item A module subprogram has an explicit interface.

  \item An internal subprogram has an explicit interface.

  \item An explicit interface may be provided by an interface block.

  \end{enumerate}

  In addition, an intrinsic procedure always has an explicit interface
  by definition.

  The idiomatic Fortran way of programming makes extensive use of
  modules; every subprogram, for instance, can be in a module.  This
  provides explicit interfaces automatically, with no extra effort on
  the part of the programmer.  It should very seldom be necessary to
  write an interface block.
\end{users}

\subsection{Characteristics of Procedures}
\label{mapsub:ProcChars}

The characteristics of dummy data objects and function results as
given in section 12.2 of the Fortran standard are extended to
also include the \emph{hpf-characteristics} of such objects, which are defined
recursively as follows:

\begin{itemize}
\item A processor arrangement has one hpf-characteristic: its shape.

\item A template has up to three hpf-characteristics:

\begin{enumerate}
\item its shape;
\item its distribution, if explicitly stated;
\item the hpf-characteristic (i.e., the shape) of the processor
  arrangement onto which it is distributed, if explicitly stated.
\end{enumerate}

\item A dummy data object has the following hpf-characteristics:

\begin{enumerate}
\item its alignment, if explicitly stated, as well as all
  hpf-characteristics of its align target;
\item its distribution, if explicitly stated, as well as the
  hpf-characteristic (i.e., the shape) of the processor arrangement
  onto which it is distributed, if explicitly stated.
\end{enumerate}

\item A function result has the same hpf-characteristics as a dummy
  data object.  Specifically, it has the following
  hpf-characteristics:

\begin{enumerate}
\item its alignment, if explicitly stated, as well as all
  hpf-characteristics of its align target;
\item its distribution, if explicitly stated, as well as the
  hpf-characteristic (i.e., the shape) of the processor arrangement
  onto which it is distributed, if explicitly stated.
\end{enumerate}

\end{itemize}

\begin{rationale}
  In case an explicit interface is given by an interface block, the
  Fortran standard specifies what information must be specified in
  that interface block; it does this using the concept of a Fortran
  \emph{characteristic}.  Characteristics of dummy data objects, for
  instance, include their types.  Characteristics must be specified in
  interface blocks; section 12.3.2.1 of the Fortran standard states

  \begin{quote}
    An interface body specifies all of the procedure's characteristics and
    these shall be consistent with those specified in the procedure
    definition\dots
  \end{quote}

  Normally, an interface block for a procedure is a textual copy of the
  appropriate declarations of that procedure.  This section simply says
  that such a textual copy must include any explicit mapping directives
  relevant to dummy arguments of the procedure.
\end{rationale}

\section{Restrictions on Pointers and Targets}
\label{mapsub:pointers}

If, on invocation of a procedure P: (a)~a dummy argument has the
\texttt{TARGET} attribute, and (b)~the corresponding actual argument
has the \texttt{TARGET} attribute and is not an array section with a
vector subscript (and therefore is an object A or a section of an
array A), then the program is not HPF-conforming unless:
\begin{enumerate}
\item No remapping of the actual argument occurs during the call; or
\item the remainder of program execution would be unaffected if
  \begin{enumerate}
  \item\label{first-item} each pointer associated with any portion of
    the dummy argument or with any portion of A during execution of P
    were to acquire undefined pointer association status on exit from
    P; and
  \item\label{second-item} each pointer associated with any portion of
    A before the call were to acquire undefined pointer association
    status on entry to P and, if not reassigned during execution of P,
    were to be restored on exit to the pointer association status it
    had before entry.
  \end{enumerate}
\end{enumerate}

Note that if a dummy argument has the \texttt{TARGET} attribute and no
explicit mapping attributes, then the \texttt{INHERIT} attribute is
implicitly assumed (see section~\ref{INHERIT-SECTION}); therefore no
remapping occurs for such a dummy argument and there is no problem.

\begin{rationale}
  These restrictions are made in order to support the following part
  of the Fortran standard (in section 12.4.1.1 of that document) in
  the face of implicit remapping across the subprogram interface:
  \begin{quote}
    If the dummy argument does not have the \texttt{TARGET} or
    \texttt{POINTER} attribute, any pointers associated with the actual
    argument do not become associated with the corresponding dummy
    argument on invocation of the procedure.

    If the dummy argument has the \texttt{TARGET} attribute and the
    corresponding actual argument has the \texttt{TARGET} attribute but
    is not an array section with a vector subscript:
    \begin{enumerate}
    \item Any pointers associated with the actual argument become
      associated with the corresponding dummy argument on invocation of
      the procedure.

    \item When execution of the procedure completes, any pointers
      associated with the dummy argument remain associated with the actual
      argument.
    \end{enumerate}

    If the dummy argument has the \texttt{TARGET} attribute and the
    corresponding actual argument does not have the \texttt{TARGET}
    attribute or is an array section with a vector subscript, any pointers
    associated with the dummy argument become undefined when execution of
    the procedure completes.
  \end{quote}
\end{rationale}

\subsection{Example}

Here is an example that illustrates the restrictions of this section:

\CODE

      INTEGER, TARGET, DIMENSION (10) :: ACT
      INTEGER, POINTER, DIMENSON (:) :: POINTS_TO_ACT, POINTS_TO_DUM
!HPF$ DISTRIBUTE ACT(BLOCK)

      POINTS_TO_ACT => ACT
      CALL F(ACT)
      POINTS_TO_DUM(1) = 1             ! ILLEGAL

      CONTAINS
        SUBROUTINE F(DUM)
          INTEGER, TARGET, DIMENSION(10) :: DUM
        !HPF$ DISTRIBUTE DUM(CYCLIC)

          POINTS_TO_DUM => DUM
          POINTS_TO_ACT(1) = 1         ! ILLEGAL
        END SUBROUTINE
      END

\EDOC

The assignment to \texttt{POINTS_TO_DUM(1)} is illegal because it
violates item~\ref{first-item}; the assignment to
\texttt{POINTS_TO_ACT(1)} is illegal because it violates
item~\ref{second-item}.

\section{Argument Passing and Sequence Association}

For actual arguments in a procedure call, Fortran allows an array
element (scalar) to be associated with a dummy argument that is an
array.  It furthermore allows the shape of a dummy argument to differ
from the shape of the corresponding actual array argument, in effect
reshaping the actual argument via the procedure call.  Storage
sequence properties of Fortran are used to identify the values of the
dummy argument.  This feature, carried over from FORTRAN 77, has been
widely used to pass starting addresses of subarrays, rows or columns
of a larger array, to procedures.  For HPF arrays that are potentially
mapped across processors, this feature is not fully supported.

\subsection{Sequence Association Rules}

\begin{enumerate}

\item When an array element or the name of an assumed-size array is
  used as an actual argument, the associated dummy argument must be a
  scalar or specified to be a sequential array.

  An array-element designator of a nonsequential array must not be
  associated with a dummy array argument.

\item When an actual argument is an array or array section and the
  corresponding dummy argument differs from the actual argument in
  shape, then the dummy argument must be declared sequential and the
  actual array argument must be sequential.

\item An object of type character (scalar or array) is nonsequential
  if it conforms to the requirements of Definition~\ref{seq-var} of
  section~\ref{sequence-defs}.  If the length of an explicit-length
  character dummy argument differs from the length of the actual
  argument, then both the actual and dummy arguments must be
  sequential.

\item Without an explicit interface, a sequential actual may not be
  associated with a nonsequential dummy and a nonsequential actual may
  not be associated with a sequential dummy.  (This item merely
  repeats part of section~\ref{mapsub:ExplicitInterfaces}).

\end{enumerate}

\subsection{Discussion of Sequence Association}

When the shape of the dummy array argument and its associated actual
array argument differ, the actual argument must not be an expression.
There is no HPF mechanism for declaring that the value of an
array-valued expression is sequential.  In order to associate such an
expression as an actual argument with a dummy argument of different
rank, the actual argument must first be assigned to a named array
variable that is forced to be sequential according to
Definition~\ref{seq-var} of section~\ref{sequence-defs}.

\subsection{Examples of Sequence Association}

Given the following subroutine fragment:
                                                                \CODE
      SUBROUTINE HOME (X)
      DIMENSION X (20,10)
                                                                \EDOC
By rule 1
                                                                \CODE
      CALL HOME (ET (2,1))
                                                                \EDOC
is legal only if \texttt{X} is declared sequential in \texttt{HOME}
and \texttt{ET} is sequential in the calling procedure.

Likewise, by rules 2 and 4
                                                                \CODE
      CALL HOME (ET)
                                                                \EDOC
requires either that \texttt{ET} and \texttt{X} are both sequential
arrays or that \texttt{ET} and \texttt{X} have the same shape and
(in the absence of an explicit interface) have the same sequence
attribute.

Rule 3 addresses a special consideration for  objects of type
character. Change of the length of character objects across
a call, as in

                                                                \CODE
      CHARACTER (LEN=44) one_long_word
      one_long_word = 'Chargoggagoggmanchaugagoggchaubunagungamaugg'
      CALL webster(one_long_word)

      SUBROUTINE webster(short_dictionary)
      CHARACTER (LEN=4) short_dictionary (11)
          !Note that short_dictionary(3) is 'agog', for example
                                                                \EDOC

\noindent
is conceptually legal in Fortran. In HPF, both the actual argument and
dummy argument must be sequential.
(Chargoggagoggmanchaugagoggchaubunagungamaugg is the original Nipmuc
name for what is now called Lake Webster in Massachusetts.)

---------------------------------------------------------------------------
To (un)subscribe to this list, send mail to [email-masked].
Leave the subject line blank, and in the body put the line
(un)subscribe <email-address>
---------------------------------------------------------------------------