Fortran Support Through the mpi Module (original) (raw)
Up: Fortran Support Next: Fortran Support Through the mpif.h Include File Previous: Fortran Support Through the mpi_f08 Module
An MPI implementation providing a Fortran interface must provide a module named mpi that can be used in a Fortran program. Within all MPI function specifications, the second of the set of two Fortran routine interface specifications is provided by this module. This module must:
- Define all named MPI constants
- Declare MPI functions that return a value.
- 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 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 MPI for Different Fortran Standard Versions for more details.
- Define all MPI handles as type INTEGER.
- Define the derived type MPI_Status and all named handle types that are used in the mpi_f08 module. For these named handle types, overload the operators .EQ. and .NE. to allow handle comparison via the .EQ., .NE., == and /= operators.
Rationale.
They are needed only when the application converts old-style INTEGER handles into new-style handles with a named type. ( End of rationale.)
- A high quality MPI implementation may enhance the interface by using the ASYNCHRONOUS attribute in the same way as in the mpi_f08 module if it is supported by the underlying compiler.
- Set the LOGICAL compile-time constant MPI_ASYNC_PROTECTS_NONBLOCKING to .TRUE.if the ASYNCHRONOUS attribute is used in all nonblocking interfaces and the underlying Fortran compiler supports the ASYNCHRONOUSattribute for MPI communication (as part of TS 29113), otherwise to .FALSE..
Advice to users.
For an MPI implementation that fully supports nonblocking calls with the ASYNCHRONOUS attribute for choice buffers, an existing MPI-2.2 application may fail to compile even if it compiled and executed with expected results with an MPI-2.2 implementation. One reason may be that the application uses ``contiguous'' but not ``simply contiguous'' ASYNCHRONOUS arrays as actual arguments for choice buffers of nonblocking routines, e.g., by using subscript triplets with stride one or specifying (1:n)for a whole dimension instead of using (:). This should be fixed to fulfill the Fortran constraints for ASYNCHRONOUSdummy arguments. This is not considered a violation of backward compatibility because existing applications can not use the ASYNCHRONOUS attribute to protect nonblocking calls. Another reason may be that the application does not conform either to MPI-2.2, or to MPI-3.0, or to the Fortran standard, typically because the program forces the compiler to perform copy-in/out for a choice buffer argument in a nonblocking MPI call. This is also not a violation of backward compatibility because the application itself is non-conforming. See Section Problems Due to Data Copying and Sequence Association with Subscript Triplets for more details. ( End of advice to users.)
- A high quality MPI implementation may enhance the interface by using TYPE(*), DIMENSION(..) choice buffer dummy arguments instead of using non-standardized extensions such as !$PRAGMA IGNORE_TKRor a set of overloaded functions as described by M. Hennecke in [28], if the compiler supports this TS 29113 language feature. See Section MPI for Different Fortran Standard Versions for further details.
- Set the LOGICAL compile-time constant MPI_SUBARRAYS_SUPPORTED to .TRUE.if all choice buffer arguments in all nonblocking, split collective and persistent communication routines are declared with TYPE(*), DIMENSION(..), otherwise set it to .FALSE.. When MPI_SUBARRAYS_SUPPORTED is defined as .TRUE., non-contiguous sub-arrays can be used as buffers in nonblocking routines.
- Set the MPI_SUBARRAYS_SUPPORTED compile-time constant to .FALSE. and declare choice buffers with a compiler-dependent mechanism that overrides type checking if the underlying Fortran compiler does not support the TS 29113 assumed-type and assumed-rank features. In this case, the use of non-contiguous sub-arrays in nonblocking calls may be disallowed. See Section MPI for Different Fortran Standard Versions for details.
An MPI implementation may provide other features in the mpi module that enhance the usability of MPI while maintaining adherence to the standard. For example, it may provide INTENT information in these interface blocks.
Advice to implementors.
The appropriate
INTENT
may be different from what is given in the MPI language-neutral bindings. Implementations must choose
INTENT
so that the function adheres to the MPI standard, e.g., by defining the
INTENT
as provided in the
mpi_f08
bindings. ( End of advice to implementors.)
Rationale.
The intent given by the MPI generic interface is not precisely defined and does not in all cases correspond to the correct Fortran
INTENT
. For instance, receiving into a buffer specified by a datatype with absolute addresses may require associating MPI_BOTTOMwith a dummy
OUT
argument. Moreover, ``constants'' such as MPI_BOTTOM and MPI_STATUS_IGNORE are not constants as defined by Fortran, but ``special addresses'' used in a nonstandard way. Finally, the MPI-1 generic intent was changed in several places in MPI-2. For instance, MPI_IN_PLACE changes the intent of an
OUT
argument to be
INOUT
. ( End of rationale.)
Advice to implementors.
The Fortran 2008 standard illustrates in its Note 5.17 that ``INTENT(OUT) means that the value of the argument after invoking the procedure is entirely the result of executing that procedure. If an argument should retain its value rather than being redefined, INTENT(INOUT) should be used rather than INTENT(OUT), even if there is no explicit reference to the value of the dummy argument. Furthermore, INTENT(INOUT) is not equivalent to omitting the INTENT attribute, because INTENT(INOUT) always requires that the associated actual argument is definable.'' Applications that include mpif.h may not expect that INTENT(OUT) is used. In particular, output array arguments are expected to keep their content as long as the MPI routine does not modify them. To keep this behavior, it is recommended that implementations not use INTENT(OUT)in the mpi module and the mpif.h include file, even though INTENT(OUT) is specified in an interface description of the mpi_f08 module. ( End of advice to implementors.)
Up: Fortran Support Next: Fortran Support Through the mpif.h Include File Previous: Fortran Support Through the mpi_f08 Module
Return to MPI-3.1 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-3.1 of June 4, 2015
HTML Generated on June 4, 2015