Create a gist now

Instantly share code, notes, and snippets.

MPI 3.1 chapter 17 draft, diff from MPI-3.0
Index: chap-binding/binding-2.tex
===================================================================
--- chap-binding/binding-2.tex (revision 1802)
+++ chap-binding/binding-2.tex (revision 1948)
@@ -100,7 +100,7 @@
Section~\ref{f90:mpif08} through~\ref{f90:basic} define the Fortran support methods.
The Fortran interfaces of each \MPI/ routine are shorthands.
Section~\ref{sec:f90:linker-names} defines the corresponding full
-interface specification together with the used linker names and implications
+interface specification together with the specific procedure names and implications
for the profiling interface.
Section~\ref{sec:f90:different-fortran-versions} the implementation
of the \MPI/ routines for different versions of the Fortran standard.
@@ -154,7 +154,7 @@
\code{mpi\_f08} module.
\end{users}
\end{itemize}
-\item Define all \MPI/ handles with uniquely named handle types
+\item Define the derived type \ftype{MPI\_Status}, and define all \MPI/ handles with uniquely named handle types
(instead of \ftype{INTEGER} handles, as in the \code{mpi} module).
This is reflected in the first Fortran
binding in each \MPI/ function definition throughout this document
@@ -220,7 +220,7 @@
assumed-size array and the actual argument is a strided array,
the call may be implemented with copy-in and copy-out
of the argument. In the case of \ftype{INTENT(OUT)} the copy-in may
-be suppressed by the optimization and the routine is starts execution using
+be suppressed by the optimization and the routine starts execution using
an array of undefined values. If the routine stores fewer
elements into the dummy argument than is provided in the actual
argument, then the remaining locations are overwritten with these
@@ -278,11 +278,6 @@
can be used in an implementation with assumed-type and assumed-rank
argument in an explicit interface (e.g., with the \ftype{mpi\_f08} module).
-The \ftype{INTERFACE} construct in combination with \ftype{BIND(C)}
-allows the implementation of the Fortran \code{mpi\_f08} interface with a single set of portable
-wrapper routines written in C, which supports all desired features in the \code{mpi\_f08} interface.
-TS 29113 also has a provision for \ftype{OPTIONAL} arguments in \ftype{BIND(C)} interfaces.
-
A further feature useful for \MPI/ is the extension of the
semantics of the \ftype{ASYNCHRONOUS} attribute:
In F2003 and F2008, this attribute could be used only to
@@ -308,6 +303,14 @@
\item Provide explicit interfaces according to the Fortran routine interface specifications.
This module therefore guarantees compile-time argument checking
and allows positional and keyword-based argument lists.
+ If an implementation is paired with a compiler that either does
+ not support \code{TYPE(*), DIMENSION(..)} from TS 29113, or is
+ otherwise unable to ignore the types of choice buffers, then the
+ implementation must provide explicit interfaces only for MPI
+ routines with no choice buffer arguments. See
+ Section \sectionref{sec:f90:different-fortran-versions} on
+ page \pageref{sec:f90:different-fortran-versions} for more
+ details.
\item Define all \MPI/ handles as type \ftype{INTEGER}.
\item Define the derived type \const{MPI\_Status}
and all named handle types that are used in the \code{mpi\_f08} module.
@@ -514,381 +517,228 @@
of the \MPI/ routines can be used.
\end{rationale}
-\begin{implementors}
-To make \code{mpif.h} compatible with both fixed- and free-source
-forms, to allow automatic inclusion by preprocessors, and to allow
-extended fixed-form line length, it is recommended that
-the requirement of usability in free and fixed source form applications
-be met by constructing \code{mpif.h} without any continuation lines. This
-should be possible because \code{mpif.h}
-may contain
-only declarations,
-and because common block declarations can be split among several
-lines.
-The argument names may need to be shortened to keep the
-\ftype{SUBROUTINE} statement within the allowed $72-6=66$ characters, e.g.,
-
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE
- SUBROUTINE PMPI_DIST_GRAPH_CREATE_ADJACENT(a,b,c,d,e,f,g,h,i,j,k)
- ... ! dummy argument declarations
-\end{verbatim}
-This line has 65 characters and is the longest in \MPIIIIDOTO/.
-
-As long as the \MPI/ standard contains routines
-with choice buffers and a name length and argument
-count that implies that a \ftype{BIND(C)} implementation
-would need to shorten their linker names in \code{mpif.h},
-the \code{mpif.h} cannot set \const{MPI\_SUBARRAYS\_SUPPORTED} and
-\const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING} equals
-\ftype{.TRUE.}, because such shortening is invalid.
-For example,
-\mpifunc{MPI\_FILE\_WRITE\_AT\_ALL\_BEGIN} with 6 arguments,
-may be defined:
-
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE MPI_FILE_WRITE_AT_ALL_BEGIN
- SUBROUTINE MPI_X(a,b,c,d,e,f)BIND(C,NAME='MPI_File_write_at_all_begin_f')
- ... ! dummy argument declarations
-\end{verbatim}
-This would need a line length of 73 characters, i.e., the C routine name
-would need to
-be shortened by 7 characters to stay within the available 66 characters.
-Note that the name \ftype{MPI\_X} has
-no meaning for the compilation, and that
-this problem occurs only with routines with choice buffers
-implemented with the assumed-type and assumed-rank facility of TS 29113.
-To support Fortran 77 as well as Fortran 90 and later, it may be
-necessary to eliminate all comments from \code{mpif.h}.
-\end{implementors}
-
-\subsection{Interface Specifications, Linker Names and the Profiling Interface}
+\subsection{Interface Specifications, Procedure Names, and the Profiling Interface}
\label{sec:f90:linker-names}
-The Fortran interface specifications of each \MPI/ routine
+The Fortran interface specification of each \MPI/ routine
specifies the routine name that must be called by the application program,
and the names and types of the dummy arguments together with
-additional attribbutes. The rules for the linker names and
+additional attributes.
+The Fortran standard allows
+a given Fortran interface to be implemented
+with several methods, e.g., within or outside of a module,
+with or without \ftype{BIND(C)}, or the buffers with or without TS 29113.
+Such implementation decisions imply different binary interfaces
+and different specific procedure names.
+The requirements for
+several implementation schemes together with the
+rules for the specific procedure names and
its implications for the profiling interface are specified
-within this section.
-The linker name of a Fortran routine is defined as the name
-that a C routine would have if both routines would
-have the same name visible for the linker.
-A typical linker name of the Fortran routine \ffunc{FOOfoo}
-is \code{foofoo\_\_}.
-In the case of \ftype{BIND(C,NAME='...')},
-the linker name is directly defined through the external name given by
-the string.
-
-The following rules for linker names apply:
+within this section, but not the implementation details.
+
+\begin{rationale}
+This section was introduced in \MPIIIIDOTO/ on Sep.~21, 2012.
+The major goals for implementing the three
+Fortran support methods have been:
\begin{itemize}
-\item
- With the Fortran \code{mpi\_f08} module,
- if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}:
+ \item
+ Portable implementation of the wrappers
+ from the \MPI/ Fortran interfaces to the \MPI/ routines in C.
+\vspace*{-2pt}
+ \item
+ Binary backward compatible implementation path when switching
+ \const{MPI\_SUBARRAYS\_SUPPORTED} from \ftype{.FALSE.} to \ftype{.TRUE.}.
+\vspace*{-2pt}
+ \item
+ The Fortran \textsf{PMPI} interface need not be backward compatible,
+ but a method must be included that a tools layer can use to examine the
+ \MPI/ library about the specific procedure names and interfaces used.
+\vspace*{-2pt}
+ \item
+ No performance drawbacks.
+\vspace*{-2pt}
+ \item
+ Consistency between all three Fortran support methods.
+\vspace*{-2pt}
+ \item
+ Consistent with Fortran 2008 + TS 29113.
+\end{itemize}
+The design expected that all dummy arguments in the
+\MPI/ Fortran interfaces are interoperable with C according
+to Fortran 2008 + TS 29113.
+This expectation was not fulfilled.
+The \ftype{LOGICAL} arguments are not interoperable with C,
+mainly because the internal representations for \ftype{.FALSE.} and
+\ftype{.TRUE.} are compiler dependent.
+The provided interface was mainly based on \ftype{BIND(C)} interfaces
+and therefore inconsistent with Fortran.
+To be consistent with Fortran, the \ftype{BIND(C)} had to be
+removed from the callback procedure interfaces and the predefined callbacks,
+e.g., \mpifunc{MPI\_COMM\_DUP\_FN}.
+Non-\ftype{BIND(C)} procedures are also not interoperable with C,
+and therefore the \ftype{BIND(C)} had to be removed from all routines
+with \ftype{PROCEDURE} arguments,
+e.g., from \mpifunc{MPI\_OP\_CREATE}.
+
+Therefore, this section was rewritten as an erratum to \MPIIIIDOTO/.
+\end{rationale}
- The Fortran binding must use \ftype{BIND(C)} interfaces with
- an interface name identical to the language independent name,
- e.g., \mpifunc{MPI\_SEND}.
- The linker name is a combination of the C name and an
- \code{\_f08} suffix, e.g., \code{MPI\_Send\_f08}.
- Prototype example:
+A Fortran call to an \MPI/ routine shall result in a call to a procedure
+with one of the specific procedure names and calling conventions, as described in
+Table~\ref{tab:specific-fortran-proc-names} on page~\pageref{tab:specific-fortran-proc-names}.
+Case is not significant in the names.
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE
- SUBROUTINE MPI_Send(...) BIND(C,NAME='MPI_Send_f08')
-\end{verbatim}
+\begin{table}[htbp]
+\begin{center}
+\begin{tabular}{llp{10cm}}
+\hline
+No. & Specific pro- & Calling convention \\
+ & cedure name & \\
+\hline
+1A & \ffunc{MPI\_Isend\_f08}
+ & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpi-f08-module}, except that
+ in routines with a choice buffer dummy argument, this
+ dummy argument is implemented with non-standard
+ extensions like \texttt{!\$PRAGMA IGNORE\_TKR}, which
+ provides a call-by-reference argument without type, kind,
+ and dimension checking.
+\\[2pt]
+1B & \ffunc{MPI\_Isend\_f08ts}
+ & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpi-f08-module},
+ but only for routines with one or more choice buffer dummy arguments;
+ these dummy arguments are implemented
+ with \texttt{TYPE(*), DIMENSION(..)}.
+\\[2pt]
+2A & \ffunc{MPI\_ISEND}
+ & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module}, except that
+ in routines with a choice buffer dummy argument, this
+ dummy argument is implemented with non-standard
+ extensions like \texttt{!\$PRAGMA IGNORE\_TKR}, which
+ provides a call-by-reference argument without type, kind,
+ and dimension checking.
+\\[2pt]
+2B & \ffunc{MPI\_ISEND\_FTS}
+ & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module},
+ but only for routines with one or more choice buffer dummy arguments;
+ these dummy arguments are implemented
+ with \texttt{TYPE(*), DIMENSION(..)}.
+\\
+\hline
+\end{tabular}
+\vspace*{-5mm}
+\end{center}
+\caption{Specific Fortran procedure names and related calling conventions.
+\mpifunc{MPI\_ISEND} is used as an example.
+For routines without choice buffers, only 1A and 2A apply.}
+\label{tab:specific-fortran-proc-names}
+\end{table}
- \item
- With the Fortran \code{mpi\_f08} module,
- if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}
- (i.e., with a preliminary implementation of this module without TS 29113):
+Note that for the deprecated routines in
+Section~\ref{sec:deprecated:since20} on page~\pageref{sec:deprecated:since20},
+which are reported only in
+Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module},
+scheme 2A is utilized in the \texttt{mpi} module and \texttt{mpif.h},
+and also in the \texttt{mpi\_f08} module.
- The linker name of each routine is defined through the
- linker name mapping of the Fortran compiler for the name
- defined when subarrays are supported. For example,
- \code{MPI\_Send\_f08} may be mapped to \code{mpi\_send\_f08\_\_}.
- Example:
-
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE MPI_Send
- SUBROUTINE MPI_Send_f08(...)
-\end{verbatim}
-
-\item
- With the Fortran \code{mpi} module or \code{mpif.h} include file,
- if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}:
+To set \const{MPI\_SUBARRAYS\_SUPPORTED} to \ftype{.TRUE.}
+within a Fortran support method, it is required that
+all non-blocking and split-collective routines with buffer arguments
+are implemented according to 1B and 2B, i.e.,
+with \ffunc{MPI\_Xxxx\_f08ts} in the \texttt{mpi\_f08} module,
+and with \ffunc{MPI\_XXXX\_FTS} in the \texttt{mpi} module
+and the \texttt{mpif.h} include file.
- The linker name of each routine is defined through the
- linker-name mapping of the Fortran compiler.
- For example,
- \mpifunc{MPI\_SEND} may be mapped to \code{mpi\_send\_\_}.
- Example:
+The \texttt{mpi} and \texttt{mpi\_f08} modules and the \texttt{mpif.h}
+include file
+will each correspond to exactly one implementation scheme from
+Table~\ref{tab:specific-fortran-proc-names} on page~\pageref{tab:specific-fortran-proc-names}.
+However, the \MPI/ library may contain multiple implementation schemes from
+Table~\ref{tab:specific-fortran-proc-names}.
+\begin{implementors}
+This may be desirable for backwards binary compatibility
+in the scope of a single \MPI/ implementation, for example.
+\end{implementors}
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE
- SUBROUTINE MPI_SEND(...)
-\end{verbatim}
-
-\item
- With the Fortran \code{mpi} module or \code{mpif.h} include file,
- if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}:
-
- The Fortran binding must use BIND(C) interfaces with
- an interface name identical to the language independent name,
- e.g., \mpifunc{MPI\_SEND}.
- The linker name is a combination of the C name and an
- \code{\_f} suffix, e.g., \code{MPI\_Send\_f}.
- Prototype example:
-
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- INTERFACE
- SUBROUTINE MPI_SEND(...) BIND(C,NAME='MPI_Send\_f')
-\end{verbatim}
-\end{itemize}
-If the support of subarrays is different for
-the \code{mpi} module and the \code{mpif.h} include file,
-then both linker-name methods can be used in the same application.
-If the application also uses the \code{mpi\_f08} module
-and was compiled with this module
-partially before and after the subarrays were supported,
-then all four interfaces are used within the same application.
-
\begin{rationale}
After a compiler provides the facilities from TS 29113, i.e.,
-\code{TYPE(*), DIMENSION(..)},
+\texttt{TYPE(*), DIMENSION(..)},
it is possible to change the bindings within a Fortran support method
to support subarrays
-without recompiling the complete application.
+without recompiling the complete application
+provided that the previous interfaces
+with their specific procedure names are still included in the library.
Of course, only recompiled routines can benefit from the
added facilities.
There is no binary compatibility conflict
-because each interface uses its own linker names and
-all interfaces use the same constants and type definitions.
+because each interface uses its own
+specific procedure names and
+all interfaces use the same constants
+(except the value of \const{MPI\_SUBARRAYS\_SUPPORTED} and \const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING})
+and type definitions.
+After a compiler also ensures that buffer arguments of nonblocking \MPI/ operations
+can be protected through the \ftype{ASYNCHRONOUS} attribute,
+and the procedure declarations in the \texttt{mpi\_f08} and \texttt{mpi} module
+and the \texttt{mpif.h} include file declare choice buffers
+with the \ftype{ASYNCHRONOUS} attribute, then
+the value of \const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING} can be switched to \ftype{.TRUE.}
+in the module definition and include file.
\end{rationale}
-A user-written or middleware profiling routine that
-is written according to the same binding rules
-will have the same linker name, and therefore,
+\begin{users}
+Partial recompilation of user applications when upgrading \MPI/ implementations
+is a highly complex and subtle topic.
+Users are strongly advised to consult their \MPI/ implementation's documentation
+to see exactly what is --- and what is not --- supported.
+\end{users}
+
+Within the \texttt{mpi\_f08} and \texttt{mpi} modules and \texttt{mpif.h},
+for all \MPI/ procedures, a second
+procedure with the same calling conventions shall be
+supplied, except that the name is modified by prefixing with the
+letter ``P'', e.g., \ffunc{PMPI\_Isend}\mpifuncindex{PMPI\_ISEND}.
+The specific procedure names
+for these \mpifunc{PMPI\_}\mpiskipfunc{Xxxx} procedures must be different from the
+specific procedure names for the \mpiskipfunc{MPI\_Xxxx} procedures
+and are not specified by this standard.
+
+A user-written or middleware profiling routine
+should provide the same specific Fortran
+procedure names and calling conventions, and therefore
can interpose itself as the \MPI/ library routine.
-The profiling routine can internally call the matching \mpicode{PMPI}
+The profiling routine can internally call the matching \textsf{PMPI}
routine with any of its existing bindings,
-except for routines that have callback routine dummy arguments.
-In this case, the profiling software must use the same Fortran
+except for routines that have callback routine dummy arguments,
+choice buffer arguments, or that are attribute caching routines
+\mpifuncindex{MPI\_COMM\_SET\_ATTR}\mpifuncindex{MPI\_COMM\_GET\_ATTR}%
+\mpifuncindex{MPI\_WIN\_SET\_ATTR}\mpifuncindex{MPI\_CWIN\_GET\_ATTR}%
+\mpifuncindex{MPI\_TYPE\_SET\_ATTR}\mpifuncindex{MPI\_TYPE\_GET\_ATTR}%
+(\mpiskipfunc{MPI\_\textrm{\{}COMM$|$WIN$|$TYPE\textrm{\}}\_\textrm{\{}SET$|$GET\textrm{\}}\_ATTR}).
+In this case, the profiling software
+should
+invoke the corresponding \textsf{PMPI} routine using
+the same Fortran
support method as used in the calling application program,
-because the C, \code{mpi\_f08} and \code{mpi} callback
-prototypes are different.
+because the C, \texttt{mpi\_f08} and \texttt{mpi} callback
+prototypes are different or the meaning of the choice buffer
+or \mpiarg{attribute\_val} arguments are different.
-\begin{users}
-This advice is mainly for tool writers.
-Even if an \MPI/ library supports subarrays in all three Fortran
-support methods, a portable profiling layer should also provide
-the two interfaces for \const{MPI\_SUBARRAYS\_SUPPORTED}==\ftype{.FALSE.} to
-support older binary user routines that were compiled before
-TS 29113 level support was availabile.
+\begin{users}
+Although for each support method and \MPI/ routine
+(e.g., \mpifunc{MPI\_ISEND} in \texttt{mpi\_f08}),
+multiple routines may need to be provided to intercept the
+specific procedures in the \MPI/ library
+(e.g., \ffunc{MPI\_Isend\_f08} and \ffunc{MPI\_Isend\_f08ts}),
+each profiling routine itself uses only one support method
+(e.g., \texttt{mpi\_f08})
+and calls the real \MPI/ routine through the one
+\textsf{PMPI} routine defined in this support method
+(i.e., \ffunc{PMPI\_Isend} in this example).
+\end{users}
-If a user application calls \mpifunc{MPI\_SEND}, then the
-chosen Fortran support method together with
-the \MPI/ implementation decision about
-\const{MPI\_SUBARRAYS\_SUPPORTED} imply, to which
-linker name the compiler will translate this call, i.e.,
-whether the application calls
-\code{mpi\_send\_\_}, or \code{MPI\_Send\_f}, or
-\code{mpi\_send\_f08\_\_}, or \code{MPI\_Send\_f08}.
-If the profiling layer wants to be independent of
-the decision of the user program and \MPI/ implementation,
-then it should provide all four routines.
-For example:
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- SUBROUTINE MPI_SEND(...) BIND(C,NAME='MPI_Send_f')
- USE mpi
- CALL PMPI_SEND(...)
- END SUBROUTINE
-\end{verbatim}
-The \MPI/ library must provide the \mpifunc{PMPI\_SEND} routine
-according to the same rules as for providing the \mpifunc{MPI\_SEND} routine.
-\end{users}
-
\begin{implementors}
-If an implementation provides in a first step two sets of routines,
-one for the \code{mpi} module and \code{mpif.h},
-and the other for the \code{mpi\_f08} module, and both sets
-without TS 29113, i.e., \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.},
-and the implementor wants to add a TS 29113 based set of routines,
-then it is not necessary to add two full sets of routines.
-For full quality, it is enough to implement in each set only those
-routines that have a choice buffer argument.
-\end{implementors}
-
-In the case that a Fortran binding consists of multiple
-routines through function overloading, the base names
-of overloaded routines are appended by a suffix
-indicating the difference in the argument list.
-For example, \mpifunc{MPI\_ALLOC\_MEM}
-(in the \code{mpi} module and \code{mpif.h}) has an
-\ftype{INTEGER(KIND=...)} \mpiarg{baseptr} argument without a suffix.
-This routine is overloaded by a routine with
-\ftype{TYPE(C\_PTR)} \mpiarg{baseptr}
-and the suffix \code{\_CPTR}.
-The implied linker name base is \mpifunc{MPI\_ALLOC\_MEM\_CPTR}.
-It is mapped to the linker names
-\code{MPI\_Alloc\_mem\_cptr\_f},
-and, e.g.,
-\code{mpi\_alloc\_mem\_cptr\_\_}.
-Note that these routines are always called
-via the interface name \mpifunc{MPI\_ALLOC\_MEM}
-by the application within all Fortran support methods.
-
-For routines without \ftype{ASYNCHRONOUS} choice buffers and that are not
-predefined callback routines,
-the implementor can freely choose to implement the routines
-according to the rules for \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}
-or \ftype{.FALSE.}, provided that the following rule about routine grouping
-is fulfilled.
-The implementation of routines with \ftype{ASYNCHRONOUS} choice buffers
-depends on the rules for the provided Fortran support method and
-language level of the underlying compiler.
-Predefined callback routines for the \code{mpi\_f08} module must be
-implemented with \ftype{BIND(C)} interfaces, and for the \code{mpi} module
-and \code{mpif.h} without \ftype{BIND(C)}.
-
-Similar \MPI/ routines are grouped together for linker symbol scheme
-classification.
-If the peer routine of a group is available within an \MPI/ library
-with one of its possible linker names then
-all of the routines in this group must be provided according
-to the same linker name scheme.
-If the peer routine is not available through
-a linker name scheme then all other routines
-in the group must not be available through this scheme.
-
-\noindent
-Peer routines and their routine groups:
-
-\noindent
-\begin{tabular}{lp{8cm}}
-{ \mpifunc{MPI\_ALLOC\_MEM}} \dotfill &
- \rule{0mm}{1mm}\mpifunc{MPI\_ALLOC\_MEM},
- \mpifunc{MPI\_WIN\_ALLOCATE},
- \mpifunc{MPI\_WIN\_SHARED\_ALLOCATE}, and
- \mpifunc{MPI\_WIN\_SHARED\_QUERY}. \\
-{ \mpifunc{MPI\_FREE\_MEM}} \dotfill &
- Only this routine is in this group. \\
-{ \mpifunc{MPI\_GET\_ADDRESS}} \dotfill &
- Only this routine is in this group. \\
-{ \mpifunc{MPI\_SEND}} \dotfill &
- All routines with choice buffer arguments that
- are not declared as \ftype{ASYNCHRONOUS} within the \code{mpi\_f08} module. \\
-{ \mpifunc{MPI\_ISEND}} \dotfill &
- All routines with choice buffer arguments that
- are declared as \ftype{ASYNCHRONOUS} within the \code{mpi\_f08} module. \\
-{ \mpifunc{MPI\_OP\_CREATE}} \dotfill &
- Only this routine is in this group. \\
-{ \mpifunc{MPI\_REGISTER\_DATAREP}} \dotfill &
- Only this routine is in this group. \\
-{ \mpifunc{MPI\_COMM\_KEYVAL\_CREATE}} \dotfill &
- All other routines with callback function arguments. \\
-{ \mpifunc{MPI\_COMM\_DUP\_FN}\cdeclindex{MPI\_COMM\_DUP\_FN}} \dotfill &
- All predefined callback routines. \\
-{ \mpifunc{MPI\_COMM\_RANK}} \dotfill &
- All other \MPI/ routines.
-\end{tabular}
-
-\begin{implementors}
- Removed interfaces (see Chapter~\ref{chap:removed}) are in the same
- routine group as their corresponding replacement functions.
-\end{implementors}
-
-Additionally, four C preprocessor macros are available
-in \code{mpi.h} for each routine group.
-The name of the macros are the peer routine name written as in the
-list above and appended
-with one of the following suffixes and meanings:
-
-\noindent
-\begin{tabular}{lp{10cm}}
-{ \cfunc{\_mpi\_f08\_BIND\_C}} &
- The macro is set to 1 if the \ftype{BIND(C)} linker name with
- the linker suffix \ffunc{\_f08} is available for all routines
- within this group (e.g., \ffunc{MPI\_Send\_f08}), otherwise it is set to 0.\\
-{ \cfunc{\_mpi\_f08\_BIND\_F}} &
- The macro is set to 1 if the Fortran linker name with
- the linker suffix \ffunc{\_f08} is available for all routines
- within this group (e.g., \ffunc{mpi\_send\_f08\_\_}), otherwise it is set to 0.\\
-{ \cfunc{\_mpi\_BIND\_C}} \dotfill &
- The macro is set to 1 if the \ftype{BIND(C)} linker name with
- the linker suffix \ffunc{\_f} is available for all routines
- within this group (e.g., \ffunc{MPI\_Send\_f}), otherwise it is set to 0.\\
-{ \cfunc{\_mpi\_BIND\_F}} \dotfill &
- The macro is set to 1 if the Fortran linker name without
- a linker suffix is available for all routines
- within this group (e.g., \ffunc{mpi\_send\_\_}), otherwise it is set to 0.
-\end{tabular}
-
-\noindent
-For example
-%%HEADER
-%%SKIP
-%%ENDHEADER
-\begin{verbatim}
- ...
- #define MPI_SEND_mpi_f08_BIND_C 0
- #define MPI_SEND_mpi_f08_BIND_F 1
- #define MPI_SEND_mpi_BIND_C 0
- #define MPI_SEND_mpi_BIND_F 1
-
- #define MPI_ISEND_mpi_f08_BIND_C 1
- #define MPI_ISEND_mpi_f08_BIND_F 1
- #define MPI_ISEND_mpi_BIND_C 1
- #define MPI_ISEND_mpi_BIND_F 1
- ...
- #define MPI_COMM_DUP_FN_mpi_f08_BIND_C 1
- #define MPI_COMM_DUP_FN_mpi_f08_BIND_F 0
- #define MPI_COMM_DUP_FN_mpi_BIND_C 0
- #define MPI_COMM_DUP_FN_mpi_BIND_F 1
- ...
-\end{verbatim}
-shows, that
+If all of the following conditions are fulfilled:
\begin{itemize}
-\item the routines in the \mpifunc{MPI\_SEND} group are only available through
- their Fortran linker names (e.g., \code{mpi\_send\_f08\_\_}, \code{mpi\_send\_\_},
- \code{mpi\_recv\_f08\_\_}, \code{mpi\_recv\_\_}, $\ldots$),
-\item the routines in the \mpifunc{MPI\_ISEND} group are available with all four
- interfaces: the \MPI/ library, the \code{mpi\_f08} and \code{mpi} modules (that
- provide the TS 29113 quality), and this \MPI/ library supports
- application routines that are compiled with an older \MPI/ library
- version with \cfunc{\_BIND\_C} set to 0 and \cfunc{\_BIND\_F} set to 1.
-\end{itemize}
-For the predefined callbacks, there is no choice, because
-the interfaces must fit to the callback function prototypes
-which are \ftype{BIND(C)} based for \code{mpi\_f08} and
-without \ftype{BIND(C)} for the mpi \code{module} and \code{mpif.h}.
-
-\begin{implementors}
-If all following conditions are fulfilled
-(which is the case for most compilers):
-\begin{itemize}
-\item the handles in the \code{mpi\_f08} module occupy one Fortran
+\item the handles in the \texttt{mpi\_f08} module occupy one Fortran
numerical storage unit (same as an \ftype{INTEGER} handle),
\item the internal argument passing mechanism used to pass an actual \mpiarg{ierror}
argument to a non-optional \mpiarg{ierror} dummy argument is binary
@@ -897,38 +747,176 @@
\item the internal argument passing mechanism for \ftype{ASYNCHRONOUS} and
non-\ftype{ASYNCHRONOUS} arguments is the same,
\item the internal routine call mechanism is the same for
- the Fortran and the C compilers for which the \MPI/ library is compiled,
+ the Fortran and the C compilers for which the MPI library is compiled,
\item the compiler does not provide TS 29113,
\end{itemize}
-then for the routine groups, the implementor may use the same
+then the implementor may use the same
internal routine implementations for all Fortran support
-methods but with several different linker names.
-For TS 29113 quality, new routines are needed only for
-the routine group of \mpifunc{MPI\_ISEND}.
-Typical settings for
-\cfunc{\_mpi\_f08\_BIND\_C} / \cfunc{\_mpi\_f08\_BIND\_F} / \cfunc{\_mpi\_BIND\_C} / \cfunc{\_mpi\_BIND\_F} may be:
+methods but with several different specific procedure names.
+If the accompanying Fortran compiler supports TS 29113,
+then the new routines are needed only for routines with
+choice buffer arguments. % 9/18/13 replacement for ``TS 29113 quality''
+\end{implementors}
+
+\begin{implementors}
+In the Fortran support method \texttt{mpif.h},
+compile-time argument checking
+can be also implemented for all routines.
+For \texttt{mpif.h}, the argument names are not specified through the \MPI/ standard,
+i.e., only positional argument lists are defined, and not key-word based lists.
+Due to the rule that \texttt{mpif.h}
+must be valid for fixed and free source form,
+the subroutine declaration is restricted to one line with 72 characters.
+To keep the argument lists short, each argument name can be shortened
+to a minimum of one character. With this, the two longest subroutine
+declaration statements are
+%23456789012345678901234567890123456789012345678901234567890123456789012
+\begin{verbatim}
+ SUBROUTINE PMPI_Dist_graph_create_adjacent(a,b,c,d,e,f,g,h,i,j,k)
+ SUBROUTINE PMPI_Rget_accumulate(a,b,c,d,e,f,g,h,i,j,k,l,m,n)
+\end{verbatim}
+with 71 and 66 characters.
+With buffers implemented with TS 29113, the specific procedure names have an
+additional postfix. The longest of such interface definitions is
+\begin{verbatim}
+ INTERFACE PMPI_Rget_accumulate
+ SUBROUTINE PMPI_Rget_accumulate_fts(a,b,c,d,e,f,g,h,i,j,k,l,m,n)
+\end{verbatim}
+%23456789012345678901234567890123456789012345678901234567890123456789012
+with 70 characters.
+In principle, continuation lines would be possible in \texttt{mpif.h}
+(spaces in columns 73--131, \& in column 132, and in column 6 of the
+continuation line) but this would not be valid if the source line
+length is extended with a compiler flag to 132 characters.
+Column 133 is also not available for the continuation character because
+lines longer than 132 characters are invalid with some compilers by default.
-\noindent
-{\small
-\begin{tabular}{lllll}
- & & & Upgrade for & New impl.\\
- & Without & Upgrade to& strided data& with \\
- & TS 29113& TS 29113 & optimization& TS 29113 \\[3pt]
-\cfunc{MPI\_ALLOC\_MEM\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_FREE\_MEM\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_GET\_ADDRESS\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_SEND\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & \textbf{1}/1/\textbf{1}/1 & 1/0/1/0 \\
-\cfunc{MPI\_ISEND\_...} \dotfill & 0/1/0/1 & \textbf{1}/1/\textbf{1}/1 & 1/1/1/1 & 1/0/1/0 \\
-\cfunc{MPI\_OP\_CREATE\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_REGISTER\_DATAREP\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_COMM\_KEYVAL\_CREATE\_...} & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
-\cfunc{MPI\_COMM\_DUP\_FN\_...} \dotfill & \textbf{1}/\textbf{0}/0/1 & 1/0/0/1 & 1/0/0/1 & 1/0/0/1 \\
-\cfunc{MPI\_COMM\_RANK\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0
-\end{tabular}
-}% \small
+The longest specific procedure names are
+\ffunc{PMPI\_Dist\_graph\_create\_adjacent\_f08}
+% 1234 56789 012345 6789012 345678901 2345
+and
+\ffunc{PMPI\_File\_write\_ordered\_begin\_f08ts}
+% 1234 56789 012345 67890123 456789 012345
+both with 35 characters in the \texttt{mpi\_f08} module.
+
+For example, the interface specifications together with the specific procedure names
+can be implemented with
+\mpifuncindex{MPI\_COMM\_RANK\_F08}%
+\mpifuncindex{MPI\_COMM\_RANK}%
+{\small
+\begin{verbatim}
+MODULE mpi_f08
+ TYPE, BIND(C) :: MPI_Comm
+ INTEGER :: MPI_VAL
+ END TYPE MPI_Comm
+ ...
+ INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
+ SUBROUTINE MPI_Comm_rank_f08(comm, rank, ierror)
+ IMPORT :: MPI_Comm
+ TYPE(MPI_Comm), INTENT(IN) :: comm
+ INTEGER, INTENT(OUT) :: rank
+ INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+ END SUBROUTINE
+ END INTERFACE
+END MODULE mpi_f08
+
+MODULE mpi
+ INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
+ SUBROUTINE MPI_Comm_rank(comm, rank, ierror)
+ INTEGER, INTENT(IN) :: comm ! The INTENT may be added although
+ INTEGER, INTENT(OUT) :: rank ! it is not defined in the
+ INTEGER, INTENT(OUT) :: ierror ! official routine definition.
+ END SUBROUTINE
+ END INTERFACE
+END MODULE mpi
+\end{verbatim}
+}%\small
+And if interfaces are provided in \texttt{mpif.h}, they might look like this
+(outside of any module and in fixed source format):
+{\small
+\begin{verbatim}
+!23456789012345678901234567890123456789012345678901234567890123456789012
+ INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
+ SUBROUTINE MPI_Comm_rank(comm, rank, ierror)
+ INTEGER, INTENT(IN) :: comm ! The argument names may be
+ INTEGER, INTENT(OUT) :: rank ! shortened so that the
+ INTEGER, INTENT(OUT) :: ierror ! subroutine line fits to the
+ END SUBROUTINE ! maximum of 72 characters.
+ END INTERFACE
+\end{verbatim}
+}%\small
+\end{implementors}
+
+\begin{users}
+The following is an example of how
+a user-written or middleware profiling routine
+can be implemented:
+{\small
+\begin{verbatim}
+SUBROUTINE MPI_Isend_f08ts(buf,count,datatype,dest,tag,comm,request,ierror)
+ USE :: mpi_f08, my_noname => MPI_Isend_f08ts
+ TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf
+ INTEGER, INTENT(IN) :: count, dest, tag
+ TYPE(MPI_Datatype), INTENT(IN) :: datatype
+ TYPE(MPI_Comm), INTENT(IN) :: comm
+ TYPE(MPI_Request), INTENT(OUT) :: request
+ INTEGER, OPTIONAL, INTENT(OUT) :: ierror
+ ! ... some code for the begin of profiling
+ call PMPI_Isend (buf, count, datatype, dest, tag, comm, request, ierror)
+ ! ... some code for the end of profiling
+END SUBROUTINE MPI_Isend_f08ts
+\end{verbatim}
+}%\small
+Note that this routine is used to intercept the existing specific
+procedure name \ffunc{MPI\_Isend\_f08ts} in the \MPI/ library.
+This routine must not be part of a module.
+This routine itself calls \ffunc{PMPI\_Isend}\mpifuncindex{PMPI\_ISEND}.
+The \texttt{USE} of the \texttt{mpi\_f08} module is needed for
+definitions of handle types and the interface for \ffunc{PMPI\_Isend}.
+However, this module also contains an interface definition for
+the specific procedure name \ffunc{MPI\_Isend\_f08ts} that conflicts
+with the definition of this profiling routine (i.e., the name is
+doubly defined).
+Therefore, the \texttt{USE} here specifically excludes the interface
+from the module by renaming the unused routine name in the
+\texttt{mpi\_f08} module into ``\texttt{my\_noname}'' in the scope of this routine.
+\end{users}
+\begin{users}
+The \textsf{PMPI} interface allows intercepting \MPI/ routines.
+For example, an additional \mpifunc{MPI\_ISEND} profiling wrapper
+can be provided that is called by the
+application and internally calls \mpifunc{PMPI\_ISEND}.
+There are two typical use cases: a profiling layer that is developed
+independently from the application and the \MPI/ library,
+and profiling routines that are part of the application
+and have access to the application data.
+With \MPIIIIDOTO/, new Fortran interfaces and implementation schemes
+were introduced that have several implications on how Fortran
+\MPI/ routines are internally implemented and optimized.
+For profiling layers, these schemes imply that several
+internal interfaces with different specific procedure names
+may need to be intercepted,
+as shown in the example code above.
+Therefore, for wrapper routines that
+are part of a Fortran application,
+it may be more convenient to make the name shift within
+the application, i.e., to substitute the call to the
+\MPI/ routine (e.g., \mpifunc{MPI\_ISEND}) by a call to a user-written
+profiling wrapper with a new name (e.g., \ffunc{X\_MPI\_ISEND})
+and to call the Fortran \mpifunc{MPI\_ISEND} from this wrapper,
+instead of using the \textsf{PMPI} interface.
+\end{users}
+
+\begin{implementors}
+ An implementation that provides a Fortran interface must provide a
+ combination of \MPI/ library and module or include file that uses
+ the specific procedure names as described in
+ Table~\ref{tab:specific-fortran-proc-names} on
+ page~\pageref{tab:specific-fortran-proc-names} so that the \MPI/
+ Fortran routines are interceptable as described above.
\end{implementors}
-
+
\subsection{\MPI/ for Different Fortran Standard Versions}
\label{sec:f90:different-fortran-versions}
@@ -986,7 +974,6 @@
In this preliminary interface of \mpicode{S1}, the following changes are
necessary:
\begin{itemize}
- \item The routines are not \ftype{BIND(C)}.
\item \code{TYPE(*), DIMENSION(..)} is substituted by
non-standardized extensions like \ftype{!\$PRAGMA IGNORE\_TKR}.
\item The \ftype{ASYNCHRONOUS} attribute is omitted.
@@ -994,7 +981,7 @@
substituted by \ftype{EXTERNAL}.
\end{itemize}
\item
- The linker names are specified in \sectionref{sec:f90:linker-names}.
+ The specific procedure names are specified in \sectionref{sec:f90:linker-names}.
\item
Due to the rules specified in \sectionref{sec:f90:linker-names},
choice buffer declarations should be implemented only with
@@ -1049,7 +1036,6 @@
\begin{itemize}
\item Interoperability with C, i.e.,
\begin{itemize}
- \item \ftype{BIND(C, NAME='...')} interfaces.
\item \ftype{BIND(C)} derived types.
\item The \ftype{ISO\_C\_BINDING} intrinsic type \ftype{C\_PTR}
and routine \ftype{C\_F\_POINTER}.
@@ -1056,6 +1042,9 @@
\end{itemize}
\item The ability to define an \ftype{ABSTRACT INTERFACE}
and to use it for \ftype{PROCEDURE} dummy arguments.
+ \item The ability to overload the operators \code{.EQ.} and
+ \code{.NE.} to allow the comparison of derived types (used in
+ \MPIIIIDOTO/ for \MPI/ handles).
\item The \ftype{ASYNCHRONOUS} attribute is available to protect
Fortran asynchronous I/O.
This feature is not yet used by \MPI/, but it is the basis
@@ -1079,12 +1068,11 @@
For \mpicode{S1}, only a preliminary implementation is possible.
The following changes are necessary:
\begin{itemize}
- \item The routines are not \ftype{BIND(C)}.
\item \code{TYPE(*), DIMENSION(..)} is substituted by
non-standardized extensions like \ftype{!\$PRAGMA IGNORE\_TKR}.
\end{itemize}
\item
- The linker names are specified in \sectionref{sec:f90:linker-names}.
+ The specific procedure names are specified in \sectionref{sec:f90:linker-names}.
\item
With \mpicode{S1}, the \ftype{ASYNCHRONOUS} is required as specified in
the second Fortran interfaces.
@@ -1115,10 +1103,6 @@
\item \code{TYPE(*), DIMENSION(..)} is available.
\item The \ftype{ASYNCHRONOUS} attribute is extended to protect also
nonblocking \MPI/ communication.
- \item \ftype{OPTIONAL} dummy arguments are allowed in combination with
- \ftype{BIND(C)} interfaces.
- \item \ftype{CHARACTER(LEN=*)} dummy arguments are allowed in combination with
- \ftype{BIND(C)} interfaces.
\item The array dummy argument of the \ftype{ISO\_C\_BINDING} intrinsic
\ftype{C\_F\_POINTER} is not restricted to Fortran types for which
a corresponding type in C exists.
@@ -1265,44 +1249,18 @@
nor on the declaration of application routines that are involved
in invoking \MPI/ procedures.
\end{itemize}
-All of these rules are valid independently of whether
-the \MPI/ routine interfaces in the \code{mpi\_f08} and \code{mpi} modules
-are internally defined with an \ftype{INTERFACE} or \ftype{CONTAINS}
-construct, and with or without \ftype{BIND(C)}, and also if
-\code{mpif.h} uses explicit interfaces.
+All of these rules are valid
+for the \texttt{mpi\_f08} and \texttt{mpi}
+modules and
+independently of whether
+\texttt{mpif.h} uses explicit interfaces.
\begin{implementors}
- Some of these rules are already part of the Fortran 2003 standard
- if the \MPI/ interfaces are defined without \ftype{BIND(C)}.
- Additional compiler support may be necessary if \ftype{BIND(C)}
- is used. Some of these additional requirements are defined in
- the Fortran TS 29113 \cite{fortran2008:ts29113-interop}.
- Some of these requirements for \MPIIIIDOTO/ are beyond the scope of TS 29113.
+ Some of these rules are already part of the Fortran 2003 standard,
+ some of these requirements require
+ the Fortran TS 29113 \cite{fortran2008:ts29113-interop},
+ and
+ some of these requirements for \MPIIIIDOTO/ are beyond the scope of TS 29113.
\end{implementors}
-Further requirements apply if
-the \MPI/ library internally uses \ftype{BIND(C)} routine interfaces
-(i.e., for a full implementation of \code{mpi\_f08}):
-\begin{itemize}
-\item
- Non-buffer arguments are
- \ftype{INTEGER}, \ftype{INTEGER(KIND=...)},
- \ftype{CHARACTER(LEN=*)},
- \ftype{LOGICAL},
- and \ftype{BIND(C)} derived types (handles and status in \code{mpi\_f08}),
- variables and arrays;
- function results are \ftype{DOUBLE PRECISION}.
- All these types must be valid as dummy arguments in the
- \ftype{BIND(C)} \MPI/ routine interfaces.
- When compiling an \MPI/ application, the compiler should not
- issue warnings indicating that these types may not be interoperable
- with an existing type in C.
- Some of these types are already valid in \ftype{BIND(C)} interfaces
- since Fortran 2003,
- some may be valid based on TS 29113 (e.g., \ftype{CHARACTER*(*)}).
-\item
- \ftype{OPTIONAL} dummy arguments are also valid within \ftype{BIND(C)}
- interfaces. This requirement is fulfilled if TS 29113 is fully supported
- by the compiler.
-\end{itemize}
\subsection{Additional Support for Fortran Register-Memory-Synchronization}
@@ -1316,7 +1274,7 @@
\begin{funcdef}{MPI\_F\_SYNC\_REG(buf)}
\funcarg{\INOUT}{buf}{initial address of buffer (choice)}
\end{funcdef}
-\mpifnewbind{MPI\_F\_sync\_reg(buf) BIND(C) \fargs TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf}
+\mpifnewbind{MPI\_F\_sync\_reg(buf) \fargs TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf}
\mpifbind{MPI\_F\_SYNC\_REG(buf)\fargs <type> buf(*)}
This routine has no executable statements. It must be compiled in the \MPI/ library
@@ -1471,7 +1429,7 @@
\funcarg{\OUT}{newtype}{the requested \MPI/ datatype (handle)}
\end{funcdef}
\mpibind{MPI\_Type\_create\_f90\_real(int~p, int~r, MPI\_Datatype~*newtype)}
-\mpifnewbind{MPI\_Type\_create\_f90\_real(p, r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Type\_create\_f90\_real(p, r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_TYPE\_CREATE\_F90\_REAL(P, R, NEWTYPE, IERROR)\fargs INTEGER P, R, NEWTYPE, IERROR}
This function returns a predefined \MPI/ datatype that matches a \ftype{REAL} variable
@@ -1500,7 +1458,7 @@
\end{funcdef}
\mpibind{MPI\_Type\_create\_f90\_complex(int~p, int~r, MPI\_Datatype~*newtype)}
-\mpifnewbind{MPI\_Type\_create\_f90\_complex(p, r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Type\_create\_f90\_complex(p, r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_TYPE\_CREATE\_F90\_COMPLEX(P, R, NEWTYPE, IERROR)\fargs INTEGER P, R, NEWTYPE, IERROR}
This function returns a predefined \MPI/ datatype that matches a \ftype{COMPLEX} variable
@@ -1523,7 +1481,7 @@
\funcarg{\OUT}{newtype}{the requested \MPI/ datatype (handle)}
\end{funcdef}
\mpibind{MPI\_Type\_create\_f90\_integer(int~r, MPI\_Datatype~*newtype)}
-\mpifnewbind{MPI\_Type\_create\_f90\_integer(r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Type\_create\_f90\_integer(r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_TYPE\_CREATE\_F90\_INTEGER(R, NEWTYPE, IERROR)\fargs INTEGER R, NEWTYPE, IERROR}
This function returns a predefined \MPI/ datatype that matches a \ftype{INTEGER} variable
@@ -1691,7 +1649,7 @@
Fortran where \constskip{$<$TYPE$>$} is one of
\constskip{REAL}, \constskip{INTEGER} and \constskip{COMPLEX}, and \textbf{n} is the length in bytes of the
machine representation. This datatype locally matches all variables
-of type (\textbf{typeclass}, \textbf{n}). The list of names for such types
+of type (\textbf{typeclass}, \textbf{n}) in Fortran. The list of names for such types
includes:
%%HEADER
%%SKIP
@@ -1711,7 +1669,20 @@
\end{verbatim}
One
datatype is required for each representation supported by
-the compiler. To be backward compatible with the interpretation of
+the Fortran compiler.
+
+\begin{rationale}
+ Particularly for the longer floating-point types, C and Fortran may
+ use different representations. For example, a Fortran compiler may
+ define a 16-byte \constskip{REAL} type with 33 decimal digits of
+ precision while a C compiler may define a 16-byte \constskip{long
+ double} type that implements an 80-bit (10 byte) extended
+ precision floating point value. Both of these types are 16 bytes
+ long, but they are not interoperable. Thus, these types are defined
+ by Fortran, even though C may define types of the same length.
+\end{rationale}
+
+To be backward compatible with the interpretation of
these types in \MPII/, we assume that the nonstandard declarations
\ftype{REAL*n}, \ftype{INTEGER*n}, always create a variable whose
representation is of size \textbf{n}.
@@ -1731,7 +1702,7 @@
\funcarg{\OUT}{size}{size of machine representation of that type (integer)}
\end{funcdef}
-\mpifnewbind{MPI\_Sizeof(x, size, ierror) BIND(C) \fargs TYPE(*), DIMENSION(..) :: x \\ INTEGER, INTENT(OUT) :: size \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Sizeof(x, size, ierror) \fargs TYPE(*), DIMENSION(..) :: x \\ INTEGER, INTENT(OUT) :: size \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_SIZEOF(X, SIZE, IERROR) \fargs <type> X\\INTEGER SIZE, IERROR }
This function returns the size in bytes of the machine representation of
@@ -1757,7 +1728,7 @@
\end{funcdef}
\mpibind{MPI\_Type\_match\_size(int~typeclass, int~size, MPI\_Datatype~*datatype)}
-\mpifnewbind{MPI\_Type\_match\_size(typeclass, size, datatype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: typeclass, size \\ TYPE(MPI\_Datatype), INTENT(OUT) :: datatype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Type\_match\_size(typeclass, size, datatype, ierror) \fargs INTEGER, INTENT(IN) :: typeclass, size \\ TYPE(MPI\_Datatype), INTENT(OUT) :: datatype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_TYPE\_MATCH\_SIZE(TYPECLASS, SIZE, DATATYPE, IERROR) \fargs INTEGER TYPECLASS, SIZE, DATATYPE, IERROR}
\mpiarg{typeclass} is one of \const{MPI\_TYPECLASS\_REAL},
@@ -2145,6 +2116,12 @@
\end{rationale}
\item If \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}:
+
+In this case, the use of Fortran arrays with subscript triplets as
+actual choice buffer arguments in any nonblocking \MPI/ operation
+(which also includes persistent request, and split collectives) may
+cause undefined behavior. They may, however, be used in blocking \MPI/
+operations.
Implicit in \MPI/ is the idea of a contiguous chunk of memory accessible
through a linear address space. \MPI/ copies data to and from this
@@ -2280,7 +2257,7 @@
CALL MPI_Send( A((/7,9,23,81,82/)), 5, MPI_REAL, ...)
\end{verbatim}
-Arrays with a vector subscript must not be used as actual choice buffer arguments
+Fortran arrays with a vector subscript must not be used as actual choice buffer arguments
in any nonblocking or split collective \MPI/ operations. They may, however, be used in
blocking \MPI/ operations.
@@ -2596,6 +2573,15 @@
The register optimization / code movement problem for \const{MPI\_BOTTOM}
and derived \MPI/ datatypes may occur in each blocking and nonblocking
communication call, as well as in each parallel file I/O operation.
+
+\subsubsection{Persistent Operations}
+
+With persistent requests, the buffer argument is hidden from the
+\mpifunc{MPI\_START} and \mpifunc{MPI\_STARTALL} calls, i.e., the
+Fortran compiler may move buffer accesses across the
+\mpifunc{MPI\_START} or \mpifunc{MPI\_STARTALL} call, similar to the
+\mpifunc{MPI\_WAIT} call as described in the Nonblocking Operations
+subsection in Section~\ref{sec:f90-problems:code-movements}.
\subsubsection{One-sided Communication}
@@ -3225,7 +3211,7 @@
\begin{itemize}
\item \MPI/ datatype handles with absolute addresses in combination
with \const{MPI\_BOTTOM}.
-\item Nonblocking \MPI/ operations (communication, one-sided, I/O)
+\item All nonblocking \MPI/ operations
if the internally used
pointers to the buffers are not updated by the Fortran
runtime, or if within an \MPI/ process,
@@ -3772,7 +3758,7 @@
\funcarg{\OUT}{f08\_status}{status object declared as named type}
\end{funcdef}
\mpibind{MPI\_Status\_f2f08(MPI\_Fint~*f\_status, MPI\_F08\_status *f08\_status)}
-\mpifnewbind{MPI\_Status\_f2f08(f\_status, f08\_status, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: f\_status(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status), INTENT(OUT) :: f08\_status \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror }
+\mpifnewbind{MPI\_Status\_f2f08(f\_status, f08\_status, ierror) \fargs INTEGER, INTENT(IN) :: f\_status(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status), INTENT(OUT) :: f08\_status \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror }
\mpifbind{MPI\_STATUS\_F2F08(F\_STATUS, F08\_STATUS, IERROR)\fargs INTEGER :: F\_STATUS(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status) :: F08\_STATUS \\ INTEGER IERROR}
This routine converts a Fortran \ftype{INTEGER}, \ftype{DIMENSION(MPI\_STATUS\_SIZE)} status array
@@ -3783,7 +3769,7 @@
\funcarg{\OUT}{f\_status}{status object declared as array}
\end{funcdef}
\mpibind{MPI\_Status\_f082f(MPI\_F08\_status *f08\_status, MPI\_Fint~*f\_status)}
-\mpifnewbind{MPI\_Status\_f082f(f08\_status, f\_status, ierror) BIND(C) \fargs TYPE(MPI\_Status), INTENT(IN) :: f08\_status \\ INTEGER, INTENT(OUT) :: f\_status(MPI\_STATUS\_SIZE) \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifnewbind{MPI\_Status\_f082f(f08\_status, f\_status, ierror) \fargs TYPE(MPI\_Status), INTENT(IN) :: f08\_status \\ INTEGER, INTENT(OUT) :: f\_status(MPI\_STATUS\_SIZE) \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
\mpifbind{MPI\_STATUS\_F082F(F08\_STATUS, F\_STATUS, IERROR)\fargs TYPE(MPI\_Status) :: F08\_STATUS \\ INTEGER :: F\_STATUS(MPI\_STATUS\_SIZE) \\ INTEGER IERROR}
This routine converts a Fortran \code{mpi\_f08} \ftype{TYPE(MPI\_Status)}\cdeclindex{MPI\_Status}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment