[97] | 1 | .\"Copyright 2006-2008 Sun Microsystems, Inc. |
---|
| 2 | .\" Copyright (c) 1996 Thinking Machines Corporation |
---|
| 3 | .TH MPI_Intercomm_create 3 "Dec 08, 2009" "1.4" "Open MPI" |
---|
| 4 | .SH NAME |
---|
| 5 | \fBMPI_Intercomm_create\fP \- Creates an intercommuncator from two intracommunicators. |
---|
| 6 | |
---|
| 7 | .SH SYNTAX |
---|
| 8 | .ft R |
---|
| 9 | .SH C Syntax |
---|
| 10 | .nf |
---|
| 11 | #include <mpi.h> |
---|
| 12 | int MPI_Intercomm_create(MPI_Comm \fIlocal_comm\fP, int\fI local_leader\fP, |
---|
| 13 | MPI_Comm\fI peer_comm\fP, int\fI remote_leader\fP, int\fI tag\fP, MPI_Comm\fI *newintercomm\fP) |
---|
| 14 | |
---|
| 15 | .SH Fortran Syntax |
---|
| 16 | .nf |
---|
| 17 | INCLUDE 'mpif.h' |
---|
| 18 | MPI_INTERCOMM_CREATE(\fILOCAL_COMM, LOCAL_LEADER, PEER_COMM, |
---|
| 19 | REMOTE_LEADER, TAG, NEWINTERCOMM, IERROR\fP) |
---|
| 20 | INTEGER \fILOCAL_COMM, LOCAL_LEADER, PEER_COMM, REMOTE_LEADER\fP |
---|
| 21 | INTEGER \fITAG, NEWINTERCOMM, IERROR\fP |
---|
| 22 | |
---|
| 23 | .SH C++ Syntax |
---|
| 24 | .nf |
---|
| 25 | #include <mpi.h> |
---|
| 26 | Intercomm Intracomm::Create_intercomm(int \fIlocal_leader\fP, const |
---|
| 27 | Comm& \fIpeer_comm\fP, int \fIremote_leader\fP, int \fItag\fP) const |
---|
| 28 | |
---|
| 29 | .SH INPUT PARAMTERS |
---|
| 30 | .ft R |
---|
| 31 | .TP 1i |
---|
| 32 | local_comm |
---|
| 33 | The communicator containing the process that initiates the inter-communication (handle). |
---|
| 34 | .TP 1i |
---|
| 35 | local_leader |
---|
| 36 | Rank of local group leader in local_comm (integer). |
---|
| 37 | .TP 1i |
---|
| 38 | peer_comm |
---|
| 39 | "Peer" communicator; significant only at the local_leader (handle). |
---|
| 40 | .TP 1i |
---|
| 41 | remote_leader |
---|
| 42 | Rank of remote group leader in peer_comm; significant only at the local_leader (integer). |
---|
| 43 | .TP 1i |
---|
| 44 | tag |
---|
| 45 | Message tag used to identify new intercommunicator (integer). |
---|
| 46 | |
---|
| 47 | .SH OUTPUT PARAMETERS |
---|
| 48 | .ft R |
---|
| 49 | .TP 1i |
---|
| 50 | newintercomm |
---|
| 51 | Created intercommunicator (handle). |
---|
| 52 | .ft R |
---|
| 53 | .TP 1i |
---|
| 54 | IERROR |
---|
| 55 | Fortran only: Error status (integer). |
---|
| 56 | |
---|
| 57 | .SH DESCRIPTION |
---|
| 58 | .ft R |
---|
| 59 | 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. |
---|
| 60 | .sp |
---|
| 61 | This call uses point-to-point communication with communicator peer_comm, |
---|
| 62 | and with tag tag between the leaders. Thus, care must be taken that there be no pending communication on peer_comm that could interfere with this communication. |
---|
| 63 | |
---|
| 64 | If multiple MPI_Intercomm_creates are being made, they should use different tags (more precisely, they should ensure that the local and remote leaders are using different tags for each MPI_intercomm_create). |
---|
| 65 | |
---|
| 66 | .SH NOTES |
---|
| 67 | We recommend using a dedicated peer communicator, such as a duplicate of MPI_COMM_WORLD, to avoid trouble with peer communicators. |
---|
| 68 | .sp |
---|
| 69 | The MPI 1.1 Standard contains two mutually exclusive comments on the |
---|
| 70 | input intracommunicators. One says that their repective groups must be |
---|
| 71 | disjoint; the other that the leaders can be the same process. After |
---|
| 72 | some discussion by the MPI Forum, it has been decided that the groups must |
---|
| 73 | be disjoint. Note that the |
---|
| 74 | .B reason |
---|
| 75 | given for this in the standard is |
---|
| 76 | .B not |
---|
| 77 | the reason for this choice; rather, the |
---|
| 78 | .B other |
---|
| 79 | operations on |
---|
| 80 | intercommunicators (like |
---|
| 81 | .I MPI_Intercomm_merge |
---|
| 82 | ) do not make sense if the |
---|
| 83 | groups are not disjoint. |
---|
| 84 | |
---|
| 85 | .SH ERRORS |
---|
| 86 | Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument. C++ functions 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. |
---|
| 87 | .sp |
---|
| 88 | Before the error value is returned, the current MPI error handler is |
---|
| 89 | 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. |
---|
| 90 | |
---|
| 91 | .SH SEE ALSO |
---|
| 92 | MPI_Intercomm_merge |
---|
| 93 | .br |
---|
| 94 | MPI_Comm_free |
---|
| 95 | .br |
---|
| 96 | MPI_Comm_remote_group |
---|
| 97 | .br |
---|
| 98 | MPI_Comm_remote_size |
---|
| 99 | |
---|
| 100 | |
---|