MPI Subroutine Reference

MPI_COMM_SET_NAME, MPI_Comm_set_name

Purpose

Associates a name string with a communicator.

C synopsis

#include <mpi.h>
int MPI_Comm_set_name (MPI_Comm comm, char *comm_name);

C++ synopsis

#include mpi.h
void MPI::Comm::Set_name(const char* comm_name);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_SET_NAME(INTEGER COMM, CHARACTER*(*) COMM_NAME, INTEGER IERROR)

Parameters

comm

is the communicator with the identifier to be set (handle) (INOUT)

comm_name

is the character string that is saved as the communicator's name (string) (IN)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

This subroutine lets you associate a name string with a communicator. The name is intended for use as an identifier, so when the communicator is copied or duplicated, the name does not propagate.

The character string that is passed to MPI_COMM_SET_NAME is copied to space managed by the MPI library (so it can be freed by the caller immediately after the call, or allocated on the stack). Leading spaces in the name are significant, but trailing spaces are not.

Notes

MPI_COMM_SET_NAME is a local (non-collective) operation, which only affects the name of the communicator as specified in the task 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 task where that communicator exists. However, to avoid confusion, it is a good idea to give the same name to a communicator in all of the tasks 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. An attempt to use a longer name is not an error, but will result in truncation of the name. For PE MPI, the value of MPI_MAX_OBJECT_NAME is 256.

Associating a name with a communicator has no effect on the semantics of an MPI program, and (necessarily) increases the store requirement of the program, because the names must be saved. Therefore, there is no requirement that you use this function to associate names with communicators. However, debugging and profiling MPI applications can be made easier if names are associated with communicators, as the debugger or profiler should then be able to present information in a less cryptic manner.

Errors

Fatal errors:

Invalid communicator

MPI already finalized

MPI not initialized

Related information

MPI::Comm::Clone

MPI_COMM_DUP

MPI_COMM_GET_NAME