MPI_COMM_DUP, MPI_Comm_dup

Purpose

Creates a new communicator that is a duplicate of an existing
communicator.

C synopsis

#include <mpi.h>
int MPI_Comm_dup(MPI_Comm comm,MPI_Comm *newcomm);

C++ synopsis

#include mpi.h
MPI::Cartcomm MPI::Cartcomm::Dup() const;

#include mpi.h
MPI::Graphcomm MPI::Graphcomm::Dup() const;

#include mpi.h
MPI::Intercomm MPI::Intercomm::Dup() const;

#include mpi.h
MPI::Intracomm MPI::Intracomm::Dup() const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_DUP(INTEGER COMM,INTEGER NEWCOMM,INTEGER IERROR)

Parameters

comm
     is the communicator (handle) (IN)

newcomm
     is the copy of comm (handle) (OUT)

IERROR
     is the FORTRAN return code. It is always the last argument.

Description

MPI_COMM_DUP is a collective operation that is invoked by the group
associated with comm. This subroutine duplicates the existing communicator
comm with its 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
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
and any copied cached information, but a new context.

This subroutine applies to both intracommunicators and intercommunicators.

Notes

Use this operation to produce a duplicate communication space that has the
same properties as the original communicator. This includes attributes and
topologies.

This subroutine is valid even if there are pending point-to-point
communications involving the communicator comm.

Remember that MPI_COMM_DUP is collective on the input communicator, so it
is erroneous for a thread to attempt to duplicate a communicator that is
simultaneously involved in an MPI_COMM_DUP or any collective on some other
thread.

Errors

Conflicting collective operations on communicator

A copy_fn did not return MPI_SUCCESS

A delete_fn did not return MPI_SUCCESS

Invalid communicator

MPI not initialized

MPI already finalized

Related information

     MPI::Comm::Clone
     MPI_KEYVAL_CREATE