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

This section was introduced in MPI-3.0 on Sep. 21, 2012. The major goals for implementing the three Fortran support methods have been:

• 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 2008 + TS 29113.

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 20 . Case is not significant in the names.

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. Note that for the deprecated routines in Section Deprecated since MPI-2.0 , which are reported only in Annex Fortran Bindings with mpif.h or the mpi Module , scheme 2A is utilized in the mpi module and mpif.h, and also in the mpi_f08 module.

To set MPI_SUBARRAYS_SUPPORTED to .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 MPI_Xxxx_f08ts in the mpi_f08 module, and with MPI_XXXX_FTS in the mpi module and the mpif.h include file.

The mpi and mpi_f08 modules and the mpif.h include file will each correspond to exactly one implementation scheme from Table 20 . However, the MPI library may contain multiple implementation schemes from Table 20 .
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 from TS 29113, i.e., TYPE(*), DIMENSION(..), 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 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 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., 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 non-optional 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,
• the compiler does not provide TS 29113,

In the 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 two longest subroutine declaration statements are

      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) 

      INTERFACE  PMPI_Rget_accumulate 
      SUBROUTINE PMPI_Rget_accumulate_fts(a,b,c,d,e,f,g,h,i,j,k,l,m,n) 

The longest specific procedure names are PMPI_Dist_graph_create_adjacent_f08 and PMPI_File_write_ordered_begin_f08ts both with 35 characters in the mpi_f08 module.

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

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 

!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 

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

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 

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