20.3.4. Transfer of Handles

Handles are passed between Fortran and C by using an explicit C wrapper to convert Fortran handles to C handles. There is no direct access to C handles in Fortran.

The type definition MPI_Fint is provided in C for an integer of the size that matches a Fortran INTEGER; usually, MPI_Fint will be equivalent to int. With the Fortran mpi module or the (deprecated) mpif.h include file, a Fortran handle is a Fortran INTEGER value that can be used in the following conversion functions. With the Fortran mpi_f08 module, a Fortran handle is a BIND(C) derived type that contains an INTEGER component named MPI_VAL. This INTEGER value can be used in the following conversion functions.

The following functions are provided in C to convert from a Fortran communicator handle (which is an integer) to a C communicator handle, and vice versa.

C binding
(MPI_Fint comm) MPI_Comm_f2c
MPI_COMM_F2C

If comm is a valid Fortran handle to a communicator, then MPI_Comm_f2c returns a valid C handle to that same communicator; if comm = MPI_COMM_NULL (Fortran value), then MPI_Comm_f2c returns a null C handle; if comm is an invalid Fortran handle, then MPI_Comm_f2c returns an invalid C handle.

(MPI_Comm comm) MPI_Comm_c2f
MPI_COMM_C2F

The function MPI_Comm_c2f translates a C communicator handle into a Fortran handle to the same communicator; it maps a null handle into a null handle and an invalid handle into an invalid handle.

Similar functions are provided for the other types of opaque objects.

(MPI_Fint datatype) MPI_Type_f2c
MPI_TYPE_F2C

(MPI_Datatype datatype) MPI_Type_c2f
MPI_TYPE_C2F

(MPI_Fint group) MPI_Group_f2c
MPI_GROUP_F2C

(MPI_Group group) MPI_Group_c2f
MPI_GROUP_C2F

(MPI_Fint request) MPI_Request_f2c
MPI_REQUEST_F2C

(MPI_Request request) MPI_Request_c2f
MPI_REQUEST_C2F

(MPI_Fint file) MPI_File_f2c
MPI_FILE_F2C

(MPI_File file) MPI_File_c2f
MPI_FILE_C2F

(MPI_Fint win) MPI_Win_f2c
MPI_WIN_F2C

(MPI_Win win) MPI_Win_c2f
MPI_WIN_C2F

(MPI_Fint op) MPI_Op_f2c
MPI_OP_F2C

(MPI_Op op) MPI_Op_c2f
MPI_OP_C2F

(MPI_Fint info) MPI_Info_f2c
MPI_INFO_F2C

(MPI_Info info) MPI_Info_c2f
MPI_INFO_C2F

(MPI_Fint errhandler) MPI_Errhandler_f2c
MPI_ERRHANDLER_F2C

(MPI_Errhandler errhandler) MPI_Errhandler_c2f
MPI_ERRHANDLER_C2F

(MPI_Fint message) MPI_Message_f2c
MPI_MESSAGE_F2C

(MPI_Message message) MPI_Message_c2f
MPI_MESSAGE_C2F

(MPI_Fint session) MPI_Session_f2c
MPI_SESSION_F2C

(MPI_Session session) MPI_Session_c2f
MPI_SESSION_C2F

Example The example below illustrates how the Fortran MPI function MPI_TYPE_COMMIT can be implemented by wrapping the C MPI function MPI_Type_commit with a C wrapper to do handle conversions. In this example a Fortran-C interface is assumed where a Fortran function is all upper case when referred to from C and arguments are passed by addresses.

! FORTRAN PROCEDURE 
SUBROUTINE MPI_TYPE_COMMIT(DATATYPE, IERR) 
INTEGER :: DATATYPE, IERR 
CALL MPI_X_TYPE_COMMIT(DATATYPE, IERR) 
RETURN 
END 

/* C wrapper */ 
 
void MPI_X_TYPE_COMMIT(MPI_Fint *f_handle, MPI_Fint *ierr) 
{ 
   MPI_Datatype datatype; 
 
   datatype = MPI_Type_f2c(*f_handle); 
   *ierr = (MPI_Fint)MPI_Type_commit(&datatype); 
   *f_handle = MPI_Type_c2f(datatype); 
   return; 
} 

The same approach can be used for all other MPI functions. The call to MPI_ XXX_f2c (resp. MPI_ XXX_c2f) can be omitted when the handle is an OUT (resp. IN) argument, rather than INOUT.

Rationale.

The design here provides a convenient solution for the prevalent case, where a C wrapper is used to allow Fortran code to call a C library, or C code to call a Fortran library. The use of C wrappers is much more likely than the use of Fortran wrappers, because it is much more likely that a variable of type INTEGER can be passed to C, than a C handle can be passed to Fortran.

Returning the converted value as a function value rather than through the argument list allows the generation of efficient inlined code when these functions are simple (e.g., the identity). The conversion function in the wrapper does not catch an invalid handle argument. Instead, an invalid handle is passed below to the library function, which, presumably, checks its input arguments. ( End of rationale.)