create_comm_from_handle Function

private function create_comm_from_handle(fhandle) result(comm)

Builds an OWNED comm_t from a caller’s Fortran MPI communicator handle.

fhandle is the plain integer a caller holds for a communicator: the result of MPI_Comm_c2f, or a communicator from the older mpi module. Under mpi_f08 it is the MPI_VAL component of MPI_Comm. It is a default integer because that is what the MPI standard makes a Fortran handle; pinning it to a specific kind would break a build whose MPI uses a different default integer width.

The communicator is DUPLICATED rather than wrapped. That is what makes the result owned: pic-mpi’s messages on it cannot be confused with the caller’s, and finalize frees only this copy, leaving the caller’s communicator untouched. Wrapping the handle directly would have finalize free a communicator pic-mpi does not own.

COLLECTIVE over the communicator fhandle names, because MPI_Comm_dup is: every rank in that communicator must call this, together.

A handle naming MPI_COMM_NULL returns an invalid comm_t and makes no MPI call.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: fhandle

Return Value type(comm_t)


Calls

proc~~create_comm_from_handle~~CallsGraph proc~create_comm_from_handle create_comm_from_handle mpi_comm_dup mpi_comm_dup proc~create_comm_from_handle->mpi_comm_dup proc~create_comm_from_mpi create_comm_from_mpi proc~create_comm_from_handle->proc~create_comm_from_mpi proc~create_null_comm create_null_comm proc~create_comm_from_handle->proc~create_null_comm mpi_comm_rank mpi_comm_rank proc~create_comm_from_mpi->mpi_comm_rank mpi_comm_size mpi_comm_size proc~create_comm_from_mpi->mpi_comm_size

Called by

proc~~create_comm_from_handle~~CalledByGraph proc~create_comm_from_handle create_comm_from_handle interface~comm_from_handle comm_from_handle interface~comm_from_handle->proc~create_comm_from_handle

Variables

Type Visibility Attributes Name Initial
type(MPI_Comm), private :: dup_comm
type(MPI_Comm), private :: given
integer(kind=int32), private :: ierr

Source Code

   function create_comm_from_handle(fhandle) result(comm)
   !! Builds an OWNED comm_t from a caller's Fortran MPI communicator handle.
   !!
   !! `fhandle` is the plain integer a caller holds for a communicator: the
   !! result of MPI_Comm_c2f, or a communicator from the older `mpi` module.
   !! Under mpi_f08 it is the MPI_VAL component of MPI_Comm. It is a default
   !! integer because that is what the MPI standard makes a Fortran handle;
   !! pinning it to a specific kind would break a build whose MPI uses a
   !! different default integer width.
   !!
   !! The communicator is DUPLICATED rather than wrapped. That is what makes
   !! the result owned: pic-mpi's messages on it cannot be confused with the
   !! caller's, and `finalize` frees only this copy, leaving the caller's
   !! communicator untouched. Wrapping the handle directly would have
   !! `finalize` free a communicator pic-mpi does not own.
   !!
   !! COLLECTIVE over the communicator `fhandle` names, because MPI_Comm_dup
   !! is: every rank in that communicator must call this, together.
   !!
   !! A handle naming MPI_COMM_NULL returns an invalid comm_t and makes no
   !! MPI call.
      integer, intent(in) :: fhandle
      type(comm_t) :: comm
      type(MPI_Comm) :: given, dup_comm
      integer(int32) :: ierr

      given%MPI_VAL = fhandle

      if (given == MPI_COMM_NULL) then
         comm = create_null_comm()
         return
      end if

      call MPI_Comm_dup(given, dup_comm, ierr)
      comm = create_comm_from_mpi(dup_comm)

   end function create_comm_from_handle