mac mpi

macx64/mpi/mpich/share/man/man3/MPI_Comm_dup.3

@@ -0,0 +1,133 @@
+.TH MPI_Comm_dup 3 "6/5/2019" " " "MPI"
+.SH NAME
+MPI_Comm_dup \-  Duplicates an existing communicator with all its cached information 
+.SH SYNOPSIS
+.nf
+int MPI_Comm_dup(MPI_Comm comm, MPI_Comm * newcomm)
+.fi
+.SH INPUT PARAMETERS
+.PD 0
+.TP
+.B comm 
+- Communicator to be duplicated (handle)
+.PD 1
+
+.SH OUTPUT PARAMETERS
+.PD 0
+.TP
+.B newcomm 
+- A new communicator over the same group as 
+.I comm
+but with a new
+context. See notes.  (handle)
+.PD 1
+
+.SH NOTES
+This routine is used to create a new communicator that has a new
+communication context but contains the same group of processes as
+the input communicator.  Since all MPI communication is performed
+within a communicator (specifies as the group of processes 
+.B plus
+the context), this routine provides an effective way to create a
+private communicator for use by a software module or library.  In
+particular, no library routine should use 
+.I MPI_COMM_WORLD
+as the
+communicator; instead, a duplicate of a user-specified communicator
+should always be used.  For more information, see Using MPI, 2nd
+edition.
+
+Because this routine essentially produces a copy of a communicator,
+it also copies any attributes that have been defined on the input
+communicator, using the attribute copy function specified by the
+.I copy_function
+argument to 
+.I MPI_Keyval_create
+\&.
+This is
+particularly useful for (a) attributes that describe some property
+of the group associated with the communicator, such as its
+interconnection topology and (b) communicators that are given back
+to the user; the attibutes in this case can track subsequent
+.I MPI_Comm_dup
+operations on this communicator.
+
+.SH THREAD AND INTERRUPT SAFETY
+
+This routine is thread-safe.  This means that this routine may be
+safely used by multiple threads without the need for any user-provided
+thread locks.  However, the routine is not interrupt safe.  Typically,
+this is due to the use of memory allocation routines such as 
+.I malloc
+or other non-MPICH runtime routines that are themselves not interrupt-safe.
+
+.SH NOTES FOR FORTRAN
+All MPI routines in Fortran (except for 
+.I MPI_WTIME
+and 
+.I MPI_WTICK
+) have
+an additional argument 
+.I ierr
+at the end of the argument list.  
+.I ierr
+is an integer and has the same meaning as the return value of the routine
+in C.  In Fortran, MPI routines are subroutines, and are invoked with the
+.I call
+statement.
+
+All MPI objects (e.g., 
+.I MPI_Datatype
+, 
+.I MPI_Comm
+) are of type 
+.I INTEGER
+in Fortran.
+
+.SH ERRORS
+
+All MPI routines (except 
+.I MPI_Wtime
+and 
+.I MPI_Wtick
+) return an error value;
+C routines as the value of the function and Fortran routines in the last
+argument.  Before the value is returned, the current MPI error handler is
+called.  By default, this error handler aborts the MPI job.  The error handler
+may be changed with 
+.I MPI_Comm_set_errhandler
+(for communicators),
+.I MPI_File_set_errhandler
+(for files), and 
+.I MPI_Win_set_errhandler
+(for
+RMA windows).  The MPI-1 routine 
+.I MPI_Errhandler_set
+may be used but
+its use is deprecated.  The predefined error handler
+.I MPI_ERRORS_RETURN
+may be used to cause error values to be returned.
+Note that MPI does 
+.B not
+guarentee that an MPI program can continue past
+an error; however, MPI implementations will attempt to continue whenever
+possible.
+
+.PD 0
+.TP
+.B MPI_SUCCESS 
+- No error; MPI routine completed successfully.
+.PD 1
+.PD 0
+.TP
+.B MPI_ERR_COMM 
+- Invalid communicator.  A common error is to use a null
+communicator in a call (not even allowed in 
+.I MPI_Comm_rank
+).
+.PD 1
+
+.SH SEE ALSO
+MPI_Comm_free, MPI_Keyval_create, MPI_Attr_put, MPI_Attr_delete,
+.br
+MPI_Comm_create_keyval, MPI_Comm_set_attr, MPI_Comm_delete_attr