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

       INCLUDE 'mpif.h'
       MPI_COMM_IDUP(COMM, NEWCOMM, REQUEST, IERROR)
            INTEGER   COMM, NEWCOMM, REQUEST, 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