Open MPI logo

MPI_Intercomm_create(3) man page (version 1.3.4)

  |   Home   |   Support   |   FAQ   |  

« Return to documentation listing



NAME

       MPI_Intercomm_create - Creates an intercommuncator from two intracommu-
       nicators.

SYNTAX


C Syntax

       #include <mpi.h>
       int MPI_Intercomm_create(MPI_Comm local_comm, int local_leader,
            MPI_Comm peer_comm, int remote_leader, int tag, MPI_Comm *newintercomm)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_INTERCOMM_CREATE(LOCAL_COMM, LOCAL_LEADER, PEER_COMM,
                 REMOTE_LEADER, TAG, NEWINTERCOMM, IERROR)
            INTEGER   LOCAL_COMM, LOCAL_LEADER, PEER_COMM, REMOTE_LEADER
            INTEGER   TAG, NEWINTERCOMM, IERROR

C++ Syntax

       #include <mpi.h>
       Intercomm Intracomm::Create_intercomm(int local_leader, const
            Comm& peer_comm, int remote_leader, int tag) const

INPUT PARAMTERS

       local_comm
                 The communicator containing the process  that  initiates  the
                 inter-communication (handle).

       local_leader
                 Rank of local group leader in local_comm (integer).

       peer_comm "Peer"  communicator;  significant  only  at the local_leader
                 (handle).

       remote_leader
                 Rank of remote group leader in peer_comm; significant only at
                 the local_leader (integer).

       tag       Message tag used to identify new intercommunicator (integer).

OUTPUT PARAMETERS

       newintercomm
                 Created intercommunicator (handle).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       This call creates an intercommunicator. It is collective over the union
       of  the  local  and  remote  groups. Processes should provide identical
       local_comm and local_leader arguments within each group. Wildcards  are
       not permitted for remote_leader, local_leader, and tag.

       This   call   uses   point-to-point   communication  with  communicator

NOTES

       We  recommend  using a dedicated peer communicator, such as a duplicate
       of MPI_COMM_WORLD, to avoid trouble with peer communicators.

       The MPI 1.1 Standard contains two mutually exclusive  comments  on  the
       input intracommunicators.  One says that their repective groups must be
       disjoint; the other that the leaders can be the  same  process.   After
       some  discussion  by the MPI Forum, it has been decided that the groups
       must be disjoint.  Note that the reason given for this in the  standard
       is  not  the  reason  for  this choice; rather, the other operations on
       intercommunicators (like MPI_Intercomm_merge ) do not make sense if the
       groups are not disjoint.

ERRORS

       Almost  all MPI routines return an error value; C routines as the value
       of the function and Fortran routines in the last  argument.  C++  func-
       tions  do  not  return  errors.  If the default error handler is set to
       MPI::ERRORS_THROW_EXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       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_Intercomm_merge
       MPI_Comm_free
       MPI_Comm_remote_group
       MPI_Comm_remote_size

1.3.4                            Nov 11, 2009          MPI_Intercomm_create(3)

« Return to documentation listing