NAME

       MPI_Comm_idup   -   Start  the  nonblocking  duplication  of an existing communicator with all its cached
       information.

SYNTAX

C Syntax

       #include <mpi.h>
       int MPI_Comm_idup(MPI_Comm comm, MPI_Comm *newcomm, MPI_Request *request)

Fortran Syntax

       USE MPI
       ! or the older form: INCLUDE 'mpif.h'
       MPI_COMM_IDUP(COMM, NEWCOMM, REQUEST, IERROR)
            INTEGER   COMM, NEWCOMM, REQUEST, IERROR

Fortran 2008 Syntax

       USE mpi_f08
       MPI_Comm_idup(comm, newcomm, request, ierror)
            TYPE(MPI_Comm), INTENT(IN) :: comm
            TYPE(MPI_Comm), INTENT(OUT) :: newcomm
            TYPE(MPI_Request), INTENT(OUT) :: request
            INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETER

       comm      Communicator (handle).

OUTPUT PARAMETERS

       newcomm   Copy of comm (handle).

       request   Communication request (handle).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       MPI_Comm_idup starts the nonblocking duplication of an existing communicator  comm  with  associated  key
       values.  For  each  key  value,  the  respective  copy  callback  function determines the attribute value
       associated with this key in the new communicator; one particular action that a copy callback may take  is
       to  delete  the  attribute from the new communicator. Returns in newcomm a new communicator with the same
       group, any copied cached information, but a new  context  (see  Section  5.7.1  of  the  MPI-1  Standard,
       "Functionality").  The  communicator  returned  in  newcomm  will  not  be available until the request is
       complete.

       The completion of a communicator duplication request can  be  determined  by  calling  any  of  MPI_Wait,
       MPI_Waitany, MPI_Test, or MPI_Testany with the request returned by this function.

NOTES

       This  operation  is used to provide a parallel library call with a duplicate communication space that has
       the same properties as the original communicator. This includes any attributes (see below) and topologies
       (see Chapter 6, "Process Topologies," in the MPI-1 Standard). This  call  is  valid  even  if  there  are
       pending  point-to-point  communications  involving the communicator comm. A typical call might involve an
       MPI_Comm_idup at the beginning of the parallel call, and an MPI_Comm_free of that duplicated communicator
       at the end of the call. Other models of communicator management are also possible.

       This call applies to both intra- and intercommunicators.

       Note that it is not defined by the MPI standard what happens if the attribute copy callback invokes other
       MPI functions.  In Open MPI, it is not valid for attribute copy callbacks (or any of their  children)  to
       add or delete attributes on the same object on which the attribute copy callback is being invoked.

ERRORS

       Almost  all  MPI  routines  return  an  error  value; C routines as the value of the function and Fortran
       routines in the last argument.

       Before the error value is returned, the current MPI error handler  is  called.  By  default,  this  error
       handler  aborts  the  MPI  job,  except  for  I/O  function errors. The error handler may be changed with
       MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values
       to be returned. Note that MPI does not guarantee that an MPI program can continue past an error.

SEE ALSO

       MPI_Comm_dup MPI_Comm_dup_with_info

4.1.6                                             Sep 30, 2023                                  MPI_Comm_idup(3)