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)
- comm
- Communicator whose identifier is to be set (handle).
- comm_name
- Character string to be used as the identifier for the
communicator (string).
OUTPUT PARAMETER¶
- IERROR
- Fortran only: Error status (integer).
DESCRIPTION¶
MPI_Comm_set_name allows a user to associate a name string with a communicator.
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 immediately 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++ 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.
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
