Subject: hpff-doc: new Chapter 3 (mappings in subroutine interfaces)

From: [email-masked] (Carl Offner)
Date: Mon, 3 Jun 1996 11:54:12 -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.
---------------------------------------------------------------------------

% File: mapping-subr.tex

% Contents:
% Mapping constructs for dummy arguments for HPF 2.0 document,
% including
%       interface rules
%       INHERIT
%       the rest of pointer mappings

% Revision history:
% Jun-03-96     First edit by Carl Offner, Digital.
%               (Rearrangements, many edits, and two new sections; see
%               the comments at the top of the chapter.)
% May-10-96     Created by Charles Koelbel, Rice University
%               (from HPF 1.2 document and HPF 2.0 proposals)

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

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

{\em
Comments on this chpater should be directed to 
Piyush Mehrotra ({\tt [email-masked]}), 
Carl Offner ({\tt [email-masked]}), 
Guy Steele ({\tt [email-masked]}),
and \\
{\tt [email-masked]}.
Please use ``{\tt Comments on Mapping in Subprogram Calls}'' as the
{\tt Subject:} line.
\par
}

\begin{new}
  \emph{This chapter has been rearranged.  I have added comments on
    actual text changes (other than the most trivial ones).  I also
    replaced ``Fortran 90'' by ``Fortran'' consistently except in the
    last paragraph, where I replaced it by ``Fortran 95'' for clarity.
    I deleted the section on explicit dynamic remapping of dummy
    arguments (i.e., the section dealing with \texttt{DYNAMIC},
    \texttt{REALIGN}, and \texttt{REDISTRIBUTE}); this section belongs
    with the approved extensions.
    Sections~\ref{mapsub:introduction} and
    \ref{mapsub:ExplicitInterfaces} (including \ref{mapsub:SameMap})
    are new.---C.O.}
\end{new}

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

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

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

The mapping of each such dummy argument may be related to the mapping
of its associated actual argument in the calling routine (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 leave
the data in place, or to force data into a new (presumably more
efficient) mapping for the duration of the subprogram's execution.

The meaning of these forms is as follows:

\begin{description}
  
\item[prescriptive] The directive describes the mapping of the dummy.
  However, the actual as passed may not have this mapping.  \emph{If
  it does not}, it is the responsibility of the subprogram to remap
  the argument as specified, and to restore the original mapping on
  exit.  (However, see the ``Advice to implementors'' below.)

  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] The directive describes the mapping of the dummy.
  It is the responsibility of the calling routine to insure that the
  actual as passed has this mapping.  (Similarly, remapping to restore
  the original mapping on exit is also done by the caller.)

  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 subroutine
  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 distributions and processor arrangements can be specified to be
prescriptive, descriptive, or transcriptive.  Alignment is more
complicated, because of the need to specify the template to 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 ALIGN directive.

\item The template is explicitly specified by a descriptive 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 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.

If remapping is necessary at a procedure interface, this fact must be
visible in the caller.  This is a consequence of the requirements for
explicit interfaces in Section~\ref{mapsub:ExplicitInterfaces}.

\begin{implementors}
  As a result of this, an implementation may choose to have all
  necessary remapping done by the caller.  This in effect eliminates
  the distinction between prescriptive and descriptive mappings.
\end{implementors}

\begin{users}
  Although it is possible to write 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 in general 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}

\begin{new}
  \emph{This section has been rewritten.  I added Chuck's suggested
    wording, even though my reading of CCI 50 indicates that no
    wording change was necessary.  But it certainly doesn't do any
    harm.---C.O.}
\end{new}

If there is an explicit interface for the called subprogram and that
interface contains mapping directives (whether prescriptive or
descriptive) for the dummy argument in question, and if a remapping of
the 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 in such a case, the mapping directives are descriptive, then it is
the responsibility of the caller to perform the necessary remapping.
That is, the caller must provide an actual argument matching such
directives, so that the descriptive directives correctly describe the
dummy arguments to the subprogram.

\begin{implementors}
In fact, an implementation may choose to have \emph{all} necessary
remapping done by the caller.
\end{implementors}

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

\begin{new}
\emph{These next sentences were taken from the section on
  \texttt{DYNAMIC} remappings, which is otherwise moved to the part of
  the document containing the approved extensions.---C.O.}
\end{new}

An overriding principle is that \emph{any mapping or 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 subprogram to change
the mapping of any object in a manner visible to its caller.

\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 the subprogram remapping or copying
  the actual argument on entry at run time in order to satisfy the
  requested distribution for the dummy.
  
\begin{new}
\emph{I added a couple of references to the ``subprogram'' in the
  previous and next items for clarity.---C.O.}
\end{new}

\item Starting with an asterisk, a \textit{dist-format-clause} or
  \textit{dist-target} is descriptive; the clause describes a
  distribution and constitutes an assertion to the language processor
  that on entry to the subprogram it will already be so.  The
  programmer claims that, for every call to the subprogram, the actual
  argument will be such that the stated distribution already describes
  the mapping of that data.  (The intent is that if the argument is
  passed by reference, no movement of the data by the subprogram will
  be necessary at run time.  All this is under the assumption that the
  language processor has observed all other directives.  While a
  conforming HPF language processor is not required to obey mapping
  directives, it should handle descriptive directives with the
  understanding that their implied assertions are relative to this
  assumption.)

\begin{new}
\emph{I deleted ``whether explicit or implicit'' in the last sentence
  of the following item, since there is no more implicit transcriptive
  behavior.---C.O.}
\end{new}

\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.)
  Note that the transcriptive case is not included in Subset HPF.
\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).  (You can't say
this in Subset HPF.)
                                                                        \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}; \texttt{THALIA} already has a
cyclic distribution, though it might be on some other processor
arrangement.
                                                                        \CODE
!HPF$ DISTRIBUTE CALLIOPE (CYCLIC) ONTO *HOMER
                                                                        \EDOC
The language processor should do whatever it takes to cause
\texttt{CALLIOPE} to have a \texttt{CYCLIC} distribution on the
processor arrangement \texttt{HOMER}; \texttt{CALLIOPE} is already
distributed onto \texttt{HOMER}, though it might be with some other
distribution format.
                                                                        \CODE
!HPF$ DISTRIBUTE MELPOMENE * ONTO *EURIPIDES
                                                                        \EDOC
\texttt{MELPOMENE} is asserted to already be distributed onto
\texttt{EURIPIDES}; use whatever distribution format the actual
argument had so, if possible, no data movement should occur.  (You
can't say this in Subset HPF.)
                                                                        \CODE
!HPF$ DISTRIBUTE CLIO *(CYCLIC) ONTO *HERODOTUS
                                                                        \EDOC
\texttt{CLIO} is asserted to already be distributed \texttt{CYCLIC}
onto \texttt{HERODOTUS} so, if possible, no data movement should
occur.
                                                                        \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.  (You can't say
this in Subset HPF.)
                                                                        \CODE
!HPF$ DISTRIBUTE ERATO * ONTO *
                                                                        \EDOC
The mapping of \texttt{ERATO} should not be changed from that of the
actual argument.  (You can't say this in Subset HPF.)
                                                                        \CODE
!HPF$ DISTRIBUTE ARTHUR_MURRAY *(CYCLIC) ONTO *
                                                                        \EDOC
\texttt{ARTHUR_MURRAY} is asserted to already be distributed
\texttt{CYCLIC} onto whatever processor arrangement the actual
argument was distributed onto, and no data movement should occur.
(You can't say this in Subset HPF.)

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

GUY - CCI 30 SAYS THERE THERE SHOULD BE A NOTE THAT `THIS'
ALSO APPLIES TO LOCAL VARIABLES.  IT ISN'T CLEAR WHAT `THIS'
IS OR HOW IT ANSWERS THE ORIGINAL CCI QUESTION - SHOULD IT
BE SOMETHING LIKE, `LOCAL VARIABLES ALIGNED WITH ARGUMENTS
IN A SIMILAR WAY WILL ALSO HAVE A SCALAR PROCESSOR 
ARRANGEMENT'?

\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.  If such a clause is
omitted and the dummy argument has the \texttt{INHERIT} attribute (see
Section~\ref{INHERIT-SECTION}), then the compiler must handle the
directive as if \texttt{*} or \texttt{ONTO~*} had been specified
explicitly.  If such a clause is omitted and the dummy does not have
the \texttt{INHERIT} attribute, then 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
\texttt{WHEEL_OF_FORTUNE} is asserted to already be \texttt{CYCLIC}.
As long as it is kept \texttt{CYCLIC}, it may be remapped onto some
other processor arrangement, but there is no reason to.
                                                                          \CODE
!HPF$ DISTRIBUTE ONTO *TV :: DAVID_LETTERMAN
                                                                          \EDOC
\texttt{DAVID_LETTERMAN} is asserted to already be distributed
on \texttt{TV} in some fashion.  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 the template with which the dummy
argument is ultimately aligned is arrived at.

\begin{new}
  \emph{This next paragraph was lifted from the TEMPLATE section of
  the mapping-base.tex file, and should be deleted from it.}
\end{new}

First, templates are not passed through the subprogram argument
interface.  The template to which a dummy argument is aligned is
always distinct from the template to which the actual argument is
aligned, though it may be a copy (see Section \ref{INHERIT-SECTION}).
On exit from a subprogram, an HPF implementation arranges that the
actual argument is aligned with the same template with which it was
aligned before the call.

Thus, a dummy argument always has a fresh template to which it is
ultimately aligned.  This template is constructed 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 specified by the
  \textit{align-target}.
  
\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} rather than a natural 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 dummy-argument-name-list
                                                                        \FNB

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

\begin{new}
  \emph{Some sentences from the old 3.10 were inserted in the next
    paragraph (which was also split into two paragraphs), and the
    corresponding section was deleted from the discussion of
    distributions.---C.O.}
\end{new}

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, the \texttt{INHERIT} attribute implies a
default distribution of \texttt{DISTRIBUTE~*~ONTO~*}.  In such a case,
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.

If on the other hand an explicit mapping directive appears for a dummy
argument with the \texttt{INHERIT} attribute, thereby overriding the
default distribution, then the actual argument must be a whole array
or an array section with no vector subscripts; it may not be an
expression of any other form.

\begin{new}
\emph{The next paragraph is not needed; it just repeats the definition
  of natural template given in the previous section.---C.O.}
\end{new}

\begin{obsolete}
If none of the attributes \texttt{INHERIT}, \texttt{ALIGN}, and
\texttt{DISTRIBUTE} is specified explicitly for a dummy argument, then
the template of the dummy argument has the same shape as the dummy
itself and the dummy argument is aligned to its template by the
identity mapping.
\end{obsolete}

An \texttt{INHERIT} directive may be combined with other directives, with
the attributes stated in any order, more or less consistent with
Fortran attribute syntax.

\subsection{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

\begin{new}
\emph{I added ``or descriptive'' in the next sentence.---C.O.}
\end{new}

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, since \texttt{BREAD} does not appear in a prescriptive
or descriptive \texttt{DISTRIBUTE} directive, it has a
\texttt{BLOCK(10)} distribution.

Here is a more complex example:
                                                                        \CODE
      LOGICAL FRUG(128),TWIST(128)
!HPF$ PROCESSORS DANCE_FLOOR(16)
!HPF$ DISTRIBUTE (BLOCK) ONTO DANCE_FLOOR::FRUG,TWIST
      CALL TERPSICHORE(FRUG(1:40:3),TWIST(1:40:3))
                                                                        \EDOC
The two array sections \texttt{FRUG(1:40:3)} and \texttt{TWIST(1:40:3)}
are mapped onto abstract processors in the same 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}

However, the
subroutine \texttt{TERPSICHORE} will view them in different ways
because it inherits the template for the second dummy but not the first:
                                                                        \CODE
      SUBROUTINE TERPSICHORE(FOXTROT,TANGO)
      LOGICAL FOXTROT(:),TANGO(:)
!HPF$ INHERIT TANGO
                                                                        \EDOC
Therefore the template of \texttt{TANGO} is a copy of the 128 element
template of the whole array \texttt{TWIST}.  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{TANGO(I)} is aligned with element 3*I-2 of the template.  But the
template of \texttt{FOXTROT} 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}

It would be reasonable to understand the mapping of
the template of \texttt{FOXTROT} to coincide with the layout of
the array section:

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

\noindent
but we shall see that this is not permitted in HPF.   Within
subroutine \texttt{TERPSICHORE} it would be correct to make the descriptive
assertion
                                                                        \CODE
!HPF$ DISTRIBUTE TANGO *(BLOCK)
                                                                        \EDOC
but it would not be correct to declare
                                                                        \CODE
!HPF$ DISTRIBUTE FOXTROT *(BLOCK)                 !Nonconforming
                                                                        \EDOC
Each of these asserts that the template of the specified dummy argument
is already distributed \texttt{BLOCK} on entry to the subroutine.  The
shape of the template for \texttt{TANGO} is \texttt{[128]}, inherited
(copied) from the array \texttt{TWIST}, whose section was passed as the
corresponding actual argument, and that template does indeed have a
\texttt{BLOCK} distribution.  But the shape of the template for
\texttt{FOXTROT} is \texttt{[14]}; the layout of the elements of the
actual argument \texttt{FRUG(1:40:3)} (3 on the first processor, 3 on
the second processor, 2 on the third processor, 3 on the fourth
processor, \dots) cannot properly be described as a \texttt{BLOCK}
distribution of a length-14 template, so the \texttt{DISTRIBUTE}
declaration for \texttt{FOXTROT} shown above would indeed be
erroneous.

On the other hand, the layout of \texttt{FRUG(1:40:3)} can be described in
terms of an alignment to a length-128 template which can be described
by an explicit \texttt{TEMPLATE} declaration (see Section
\ref{TEMPLATE-SECTION}), so the directives

                                                                        \CODE
!HPF$ PROCESSORS DANCE_FLOOR(16)
!HPF$ TEMPLATE, DISTRIBUTE(BLOCK) ONTO DANCE_FLOOR::GURF(128)
!HPF$ ALIGN FOXTROT(J) WITH *GURF(3*J-2)
                                                                        \EDOC
could be correctly included in \texttt{TERPSICHORE} to describe the
layout of \texttt{FOXTROT} on entry to the subroutine without using
an inherited template.

\subsection{ALIGN Directives}

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}, is allowed to
remain 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.

\begin{new}
\emph{I took out the phrase ``and not \texttt{REALIGN}'' at the end of the
first sentence of the next paragraph, since \texttt{REALIGN} now belongs
with the approved extensions.---C.O.}
\end{new}

If the \textit{align-spec} begins with ``\texttt{*}'', then the
\textit{alignee} must be a dummy argument and the directive must be
\texttt{ALIGN}.  The ``\texttt{*}'' indicates that the \texttt{ALIGN}
directive constitutes a guarantee on the part of the programmer that,
on entry to the subprogram, the indicated alignment will already be
satisfied by the dummy argument, without any action to remap it
required (on the part of the subprogram) at run time.  For example:
                                                                        \CODE
      SUBROUTINE GRUNGE(PLUNGE,SPONGE)
      REAL PLUNGE(1000),SPONGE(1000)
!HPF$ INHERIT SPONGE
!HPF$ ALIGN PLUNGE WITH *SPONGE
                                                                        \EDOC

This asserts that, for every \texttt{J} in the range \texttt{1:1000},
on entry to subroutine \texttt{GRUNGE}, the directives in the program
have specified that \texttt{PLUNGE(J)} is currently mapped to the same
abstract processor as \texttt{SPONGE(J)}.  (The intent is that if the
language processor has in fact honored the directives, then no
interprocessor communication on the part of the subprogram will be
required to achieve the specified alignment.)

The alignment of a general expression is up to the language processor
and therefore unpredictable by the programmer; but the alignment of
whole arrays and array sections is predictable.  In the code fragment
                                                                        \CODE
      REAL FIJI(5000),SQUEEGEE(2000)
!HPF$ ALIGN SQUEEGEE(K) WITH FIJI(2*K)
      CALL GRUNGE(FIJI(2002:4000:2),SQUEEGEE(1001:))
                                                                        \EDOC
it is true that every element of the array section
\texttt{SQUEEGEE(1001:)} is aligned with the corresponding element
of the array section \texttt{FIJI(2002:4000:2)}, so the claim made
in subroutine \texttt{GRUNGE} is satisfied by this particular call.

Under certain circumstances, it may be possible to specify that
one dummy argument be remapped if necessary and then to
specify that another dummy will then be aligned with it:
                                                                        \CODE
      SUBROUTINE MURKY(THINK, DENSE)
!HPF$ PROCESSORS GUNK(32)
!HPF$ DISTRIBUTE (BLOCK) ONTO GUNK :: DENSE
!HPF$ ALIGN WITH *DENSE :: THICK
                                                                        \EDOC
Note that the programmer cannot be justified in descriptively asserting that
\texttt{THICK} will be aligned with \texttt{DENSE} after its remapping
unless the remapping is fully specified (that is, no part of the remapping
is left to the compiler to choose).  Therefore an explicit processors
arrangement necessarily appears in the example.  The caller must ensure that
the first actual argument is appropriately mapped onto an identical
processors arrangement.

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

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

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

\begin{enumerate}

\item  Fortran does not require one, \emph{and}
  
\item No dummy argument is passed transcriptively or with the
  \texttt{INHERIT} attribute, \emph{and}

\item  Either of the following cases applies to each pair of
  corresponding actual and dummy arguments:

  \begin{enumerate}

  \item They are both implicitly mapped.

  \item They are both explicitly mapped and the mappings are the
    same.  Section~\ref{mapsub:SameMap} below defines what ``the
    mappings are the same'' means in this context.

  \end{enumerate}

  \emph{and}

\item  Either of the following cases applies to each pair of
  corresponding actual and dummy arguments:

  \begin{enumerate}

  \item Both are sequential.

  \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.
  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 by using a module.

\item by a contained subprogram;

\item 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 subroutine, 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{Explicit Mappings Without an Explicit Interface}
\label{mapsub:SameMap}

When there is no explicit interface, the actual and dummy arguments
may still be explicitly mapped (but not transcriptively or with the
\texttt{INHERIT} attribute), as long as the mappings are the same.
This must be true in a very strict sense; in particular, the mappings
must be the same whatever configuration of processors is used, and
whatever system or user defaults may be in force.  We give here the
only circumstances under which this may be said to be true.

First note that since only named objects can be mapped, the actual
argument must be a whole array or array section.  For the purposes of
the conditions below, we shall regard a whole array as a particular
kind of array section; i.e., the section each of whose subscripts is
\texttt{:}.

Denote the dummy argument by D, the actual argument by A, and the
array of which the actual argument is a section by AA (AA might be the
same as A).  Denote the templates of the dummy and the actual by TD
and TA, respectively.  Denote the processor arrangements onto which TD
and TA are distributed by PD and PA, respectively.

PD and PA must have the same shape.

Each axis of TD that is not distributed \texttt{*} must have the same
extent and the same distribution format as the corresponding axis of
TA, and conversely.  In such a case, the axis of PD onto which the
axis of TD is distributed must have the same extent as the axis of PA
onto which the axis of TA is distributed.

One of the two following cases must hold:

\begin{enumerate}
  
\item \label{mapsub:MapSameExpTmp} The dummy is described using an
  explicit named template (using a \texttt{TEMPLATE} directive); an
  example of this (\texttt{GURF}) appears in
  Section~\ref{INHERIT-SECTION}.  (Actually, in that example, an
  explicit interface would be required, but only because of the other
  argument, which is inherited.)
  
  In such a case, for each \textit{section-subscript} of A, the
  following must hold:

  \begin{itemize}
    
  \item If the \textit{section-subscript} is scalar and the array axis
    is collapsed (as by an \texttt{ALIGN} directive) then no entry
    may appear in the distribution for TD.

  \item If the \textit{section-subscript} is scalar and the array axis
    corresponds to an axis of the template TA distributed \texttt{*},
    then no entry may appear in the distribution for TD.
    
  \item If the \textit{section-subscript} is a scalar and the array
    axis corresponds to an axis of the template TA that is not
    distributed \texttt{*}, then the position on the axis of TA to
    which the scalar is aligned must correspond to the position on the
    corresponding axis of TD to which D is aligned.
    
  \item If the \textit{section-subscript} is a
    \textit{subscript-triplet} and the array axis is collapsed (as by
    an ALIGN directive), then this case can be treated \emph{as if} a
    corresponding axis, having the same extent as the axis of AA, were
    added to TA, distributed \texttt{*}; the next item in this list
    then applies.
    
  \item If the \textit{section-subscript} is a
    \textit{subscript-triplet} and the array axis corresponds to an
    axis of the template TA, then the distribution format of the axis
    of TA must be the same as the distribution format of the
    corresponding axis of TD, and corresponding elements of A along
    its axis and D along its axis must align to corresponding
    positions on the axes of TA and TD, respectively.

  \end{itemize}
  
\item Otherwise, the dummy argument's template TD is its natural
  template.  In this case the template TA of the actual must be
  coextensive with the array AA along any axes having a distribution
  format other than ``\texttt{*}.''
  
  In such a case, for each \textit{section-subscript} of A, the
  following must hold:

  \begin{itemize}

  \item If the \textit{section-subscript} is scalar and the array axis
    is collapsed (as by an \texttt{ALIGN} directive) then no entry
    may appear in the distribution for TD.

  \item If the \textit{section-subscript} is scalar and the array
    axis corresponds to an axis of TA distributed \texttt{*}, then
    no entry may appear in the distribution for the TD.
    
  \item If the \textit{section-subscript} is a
    \textit{subscript-triplet} and the array axis is collapsed (as by
    an \texttt{ALIGN} directive), then \texttt{*} must appear in the
    distribution for TD.  Further, the \textit{stride} of the
    \textit{subscript-triplet} must be 1.
    
  \item If the \textit{section-subscript} is a
    \textit{subscript-triplet} and the array axis corresponds to an
    axis of TA distributed \texttt{*}, then \texttt{*} must appear in
    the distribution for TD.  Further, consecutive elements of the
    actual argument A along the array axis must be aligned with
    consecutive elements of TA along its corresponding axis.
    
  \item If the \textit{section-subscript} is a
    \textit{subscript-triplet} \texttt{\(l\):\(u\):\(s\)} and the
    array axis corresponds to an axis of TA distributed
    \texttt{BLOCK(\(n\))} (which might have been specified as simply
    \texttt{BLOCK}, but there will be some \(n\) that describes the
    resulting distribution), then the distribution of the axis of TD
    also must be \texttt{BLOCK(\(n\))} (or \texttt{BLOCK}, as above).
    Similarly for \texttt{CYCLIC(\(n\))} and \texttt{CYCLIC}.  (This
    just repeats a constraint previously mentioned that the
    distribution formats of these axes of TA and TD have to be the
    same.)
    
    Note that the constraints that apply to this case require that
    \(l\) must be the declared lower bound, \(u\) must be the declared
    upper bound, and \(s\) must be 1; equivalently, the triplet
    \texttt{\(l\):\(u\):\(s\)} could simply have been written as
    \texttt{:}.

  \end{itemize}
  
  Note that when the dummy has a natural template, it would be
  non-conforming to have a scalar \textit{section-subscript} on an
  array axis corresponding to an axis of TA not distributed
  \texttt{*}.

\end{enumerate}

Here is an example:

The main program has a two-dimensional array \texttt{TROGGS},
which is to be processed by a subroutine one column at a time.
(Perhaps processing the entire array at once would require
prohibitive amounts of temporary space.) Each column is to be
distributed across many processors.
                                                                        \CODE
      REAL TROGGS(1024,473)
!HPF$ PROCESSORS PMAIN(8)
!HPF$ DISTRIBUTE TROGGS(BLOCK,*) ONTO PMAIN
      DO J=1,473
        CALL WILD_THING(TROGGS(:,J))
      END DO
                                                                        \EDOC
Each column of {\tt TROGGS} has a {\tt BLOCK} distribution.  The rules
listed above mean that the lack of an explicit interface is legal in
this case provided the programmer writes directives in the subprogram
as follows (either a descriptive or a prescriptive form of the
distribution directive is correct):
                                                                        \CODE
      SUBROUTINE WILD_THING(GROOVY)
      REAL GROOVY(1024)
!HPF$ PROCESSORS PSUB(8)
!HPF$ DISTRIBUTE GROOVY *(BLOCK) ONTO *PSUB
                                                                        \EDOC

\begin{users}
  These conditions are complex.  The important things to realize are
  these:

  \begin{itemize}
      
  \item 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.
      
  \item When there is an explicit interface, there are other kinds
    of pairs of mappings that can legitimately be said to be ``the
    same''.  These restrictions apply only when there is no explicit
    interface.

  \end{itemize}
\end{users}

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

\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 subroutine 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 routine.

Likewise, by rule 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 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 77 and Fortran 95. In HPF, both the
actual argument and dummy argument must be sequential.  (By the way,
``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>
---------------------------------------------------------------------------