MPI Subroutine Reference

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