Skip to content

Document legacy Fortran MPI communicator bridge for fTimer init #359

Description

@jaharris87

fTimer currently documents the supported MPI communicator contract as mpi_f08 type(MPI_Comm) and states legacy integer communicators are not accepted. That remains the right fTimer API boundary, but the docs could give legacy Fortran users a low-disruption path.

MPI mpi_f08 handles expose the standard public integer component %MPI_VAL, so user code can convert an existing legacy use mpi / mpif.h communicator handle into a type(MPI_Comm) value at a small boundary module before calling fTimer:

module ftimer_legacy_mpi_bridge
   use mpi_f08, only: MPI_Comm
   implicit none
contains
   function legacy_comm_to_f08(comm_legacy) result(comm_f08)
      integer, intent(in) :: comm_legacy
      type(MPI_Comm) :: comm_f08

      comm_f08%MPI_VAL = comm_legacy
   end function legacy_comm_to_f08
end module ftimer_legacy_mpi_bridge

Then legacy MPI applications can keep their existing MPI use and call:

use ftimer, only: ftimer_init
use ftimer_legacy_mpi_bridge, only: legacy_comm_to_f08

integer :: comm_legacy
integer :: ierr

call ftimer_init(comm=legacy_comm_to_f08(comm_legacy), ierr=ierr)

Documentation should make clear that:

  • fTimer still accepts only type(MPI_Comm) for comm=.
  • Applications using MPI_COMM_WORLD can often omit comm= entirely.
  • The conversion burden stays in user code, not in fTimer overload resolution.
  • This is distinct from MPI_Comm_f2c, which converts a Fortran integer handle to a C MPI handle and is not needed for the pure-Fortran mpi_f08 bridge.

Likely docs to touch: README.md, docs/semantics.md, and/or docs/troubleshooting.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions