20.1.5. Interface Specifications, Procedure Names, and the Profiling Interface

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 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 BIND(C), or the buffers with or without Fortran 2018 (as successor of Fortran 2008 with 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, but not the implementation details.

Rationale.

When this section was originally introduced in MPI-3.0, the major goals for the three Fortran support methods were:

• Portable implementation of the wrappers from the MPI Fortran interfaces to the MPI routines in C.
• Binary backward compatible implementation path when switching MPI_SUBARRAYS_SUPPORTED from .FALSE. to .TRUE..
• The Fortran 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.
• No performance drawbacks.
• Consistency between all three Fortran support methods.
• Consistent with Fortran 2018.

Therefore, this section was rewritten as an erratum to MPI-3.0. ( End of rationale.)
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 28. Case is not significant in the names.

Table 28:

Specific Fortran procedure names and related calling conventions. MPI_ISEND is used as an example. For routines without choice buffers, only 1A and 2A apply.

To set MPI_SUBARRAYS_SUPPORTED to .TRUE. within a Fortran support method, it is required that all nonblocking and split-collective routines with buffer arguments are implemented according to 1B and 2B, i.e., with MPI_Xxxx_f08ts in the mpi_f08 module, and with MPI_XXXX_FTS in the mpi module and the (deprecated) mpif.h include file.

The mpi and mpi_f08 modules and the (deprecated) mpif.h include file will each correspond to exactly one implementation scheme from Table 28. However, the MPI library may contain multiple implementation schemes from Table 28.
Advice to implementors.

This may be desirable for backwards binary compatibility in the scope of a single MPI implementation, for example. ( End of advice to implementors.)

Rationale.

After a compiler provides the facilities TYPE(*), DIMENSION(..) from Fortran 2018, it is possible to change the bindings within a Fortran support method to support subarrays 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 specific procedure names and all interfaces use the same constants (except the value of MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING) and type definitions. After a compiler also ensures that buffer arguments of nonblocking MPI operations can be protected through the ASYNCHRONOUS attribute, and the procedure declarations in the mpi_f08 and mpi module and the (deprecated) mpif.h include file declare choice buffers with the ASYNCHRONOUS attribute, then the value of MPI_ASYNC_PROTECTS_NONBLOCKING can be switched to .TRUE. in the module definition and include file. ( End of rationale.)

Advice to 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 of advice to users.)
Within the mpi_f08 and mpi modules and (deprecated) mpif.h include file, 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., PMPI_Isend. The specific procedure names for these PMPI_ Xxxx procedures must be different from the specific procedure names for the 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 PMPI routine with any of its existing bindings, except for routines that have callback routine dummy arguments, choice buffer arguments, or that are attribute caching routines ( MPI_{COMM|WIN|TYPE}_{SET|GET}_ATTR). In this case, the profiling software should invoke the corresponding PMPI routine using the same Fortran support method as used in the calling application program, because the C, mpi_f08 and mpi callback prototypes are different or the meaning of the choice buffer or attribute_val arguments are different.

Advice to users.

Although for each support method and MPI routine (e.g., MPI_ISEND in mpi_f08), multiple routines may need to be provided to intercept the specific procedures in the MPI library (e.g., MPI_Isend_f08 and MPI_Isend_f08ts), each profiling routine itself uses only one support method (e.g., mpi_f08) and calls the real MPI routine through the one PMPI routine defined in this support method (i.e., PMPI_Isend in this example). ( End of advice to users.)

Advice to implementors.

If all of the following conditions are fulfilled:

• the handles in the mpi_f08 module occupy one Fortran numerical storage unit (same as an INTEGER handle),
• the internal argument passing mechanism used to pass an actual ierror argument to a nonoptional ierror dummy argument is binary compatible to passing an actual ierror argument to an ierror dummy argument that is declared as OPTIONAL,
• the internal argument passing mechanism for ASYNCHRONOUS and non- ASYNCHRONOUS arguments is the same,
• the internal routine call mechanism is the same for the Fortran and the C compilers for which the MPI library is compiled, and
• the compiler does not provide the appropriate features from Fortran 2018,

In the (deprecated) Fortran support method mpif.h, compile-time argument checking can be also implemented for all routines. For 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 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 three longest subroutine declaration statements are

     SUBROUTINE PMPI_DIST_GRAPH_CREATE_ADJACENT(a,b,c,d,e,f,g,h,i,j,k) 
     SUBROUTINE PMPI_NEIGHBOR_ALLTOALLW_INIT(a,b,c,d,e,f,g,h,i,j,k,l) 
     SUBROUTINE PMPI_NEIGHBOR_ALLTOALLV_INIT(a,b,c,d,e,f,g,h,i,j,k,l) 

     INTERFACE  PMPI_NEIGHBOR_ALLTOALLW_INIT 
     SUBROUTINE PMPI_NEIGHBOR_ALLTOALLW_INIT_F(a,b,c,d,e,f,g,h,i,j,j,k) 
     INTERFACE  PMPI_NEIGHBOR_ALLGATHERV_INIT 
     SUBROUTINE PMPI_NEIGHBOR_ALLGATHERV_INIT_F(a,b,c,d,e,f,g,h,i,j,k) 
     INTERFACE  PMPI_RGET_ACCUMULATE 
     SUBROUTINE PMPI_RGET_ACCUMULATE_FTS(a,b,c,d,e,f,g,h,i,j,k,l,m,n) 

If an implementation applies the rules of Table 28 also for the PMPI interface, then the longest specific procedure name is PMPI_Reduce_scatter_block_init_c_f08ts with 38 characters in the mpi_f08 module.

For example, the interface specifications together with the specific procedure names can be implemented with

And if interfaces are provided in mpif.h, they might look like this (outside of any module and in fixed source format):

( End of advice to implementors.)

Advice to users.

The following is an example of how a user-written or middleware profiling routine can be implemented:

Note that this routine is used to intercept the existing specific procedure name MPI_Isend_f08ts in the MPI library. This routine must not be part of a module. This routine itself calls PMPI_Isend. The USE of the mpi_f08 module is needed for definitions of handle types and the interface for PMPI_Isend. However, this module also contains an interface definition for the specific procedure name MPI_Isend_f08ts that conflicts with the definition of this profiling routine (i.e., the name is doubly defined). Therefore, the USE here specifically excludes the interface from the module by renaming the unused routine name in the mpi_f08 module into ``my_noname'' in the scope of this routine. ( End of advice to users.)

Advice to users.

The PMPI interface allows intercepting MPI routines. For example, an additional MPI_ISEND profiling wrapper can be provided that is called by the application and internally calls 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 MPI-3.0, 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., MPI_ISEND) by a call to a user-written profiling wrapper with a new name (e.g., X_MPI_ISEND) and to call the Fortran MPI_ISEND from this wrapper, instead of using the PMPI interface. ( End of advice to users.)

Advice to 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 28 so that the MPI Fortran routines are interceptable as described above. ( End of advice to implementors.)