MPI_Comm_set_name(3OpenMPI) MPI_Comm_set_name(3OpenMPI)
NAME
MPI_Comm_set_name - Associates a name with a communicator.
SYNTAX
C Syntax
#include <mpi.h>
int MPI_Comm_set_name(MPI_Comm comm, char *comm_name)
Fortran Syntax
INCLUDE 'mpif.h'
MPI_COMM_SET_NAME(COMM, COMM_NAME, IERROR)
INTEGER COMM, IERROR
CHARACTER*(*) COMM_NAME
C++ Syntax
#include <mpi.h>
void MPI::Comm::Set_name(const char* comm_name)
INPUT/OUTPUT PARAMETER
comm Communicator whose identifier is to be set (handle).
INPUT PARAMETER
comm_name Character string to be used as the identifier for the commu-
nicator (string).
OUTPUT PARAMETER
IERROR Fortran only: Error status (integer).
DESCRIPTION
MPI_Comm_set_name allows a user to associate a name string with a com-
municator. The character string that is passed to MPI_Comm_set_name is
saved inside the MPI library (so it can be freed by the caller immedi-
ately after the call, or allocated on the stack). Leading spaces in
name are significant, but trailing ones are not.
MPI_Comm_set_name is a local (noncollective) operation, which affects
only the name of the communicator as seen in the process that made the
MPI_Comm_set_name call. There is no requirement that the same (or any)
name be assigned to a communicator in every process where it exists.
The length of the name that can be stored is limited to the value of
MPI_MAX_OBJECT_NAME in Fortran and MPI_MAX_OBJECT_NAME-1 in C and C++
(to allow for the null terminator). Attempts to set names longer than
this will result in truncation of the name. MPI_MAX_OBJECT_NAME must
have a value of at least 64.
NOTES
Since MPI_Comm_set_name is provided to help debug code, it is sensible
to give the same name to a communicator in all of the processes where
it exists, to avoid confusion.
Regarding name length, under circumstances of store exhaustion, an
attempt to set a name of any length could fail; therefore, the value of
MPI_MAX_OBJECT_NAME should be viewed only as a strict upper bound on
the name length, not a guarantee that setting names of less than this
length will always succeed.
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_Comm_get_name(3)
Open MPI 1.2 September 2006 MPI_Comm_set_name(3OpenMPI)
Mac OS X 10.6 - Generated Thu Sep 17 20:12:55 CDT 2009