MPI Subroutine Reference

MPI_COMM_GET_ATTR, MPI_Comm_get_attr

Purpose

Retrieves the communicator attribute value identified by the key.

C synopsis

#include <mpi.h>
int MPI_Comm_get_attr (MPI_Comm comm, int comm_keyval,
                       void *attribute_val, int *flag);

C++ synopsis

#include mpi.h
bool MPI::Comm::Get_attr(int comm_keyval, void* attribute_val) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_GET_ATTR(INTEGER COMM, INTEGER COMM_KEYVAL, INTEGER ATTRIBUTE_VAL,
                  LOGICAL FLAG, INTEGER IERROR)

Parameters

comm

is the communicator to which the attribute is attached (handle) (IN)

comm_keyval

is the key value (integer) (IN)

attribute_val

is the attribute value, unless flag = false (OUT)

flag

is false if there is no attribute associated with the key (logical) (OUT)

IERROR

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

Description

This subroutine retrieves an attribute value by key. If there is no key with value keyval, the call is erroneous. However, the call is valid if there is a key value keyval, but no attribute is attached on comm for that key. In this case, the call returns flag = false.

Notes

MPI_COMM_GET_ATTR supersedes MPI_ATTR_GET.

MPI_COMM_GET_ATTR does not interoperate with MPI_ATTR_GET. The FORTRAN bindings for MPI-1 caching functions presume that an attribute is an INTEGER. The MPI-2 caching bindings use INTEGER (KIND=MPI_ADDRESS_KIND). In an MPI implementation that uses 64-bit addresses and 32-bit INTEGERS, the two formats would be incompatible.

The implementation of MPI_COMM_SET_ATTR and MPI_COMM_GET_ATTR involves saving a single word of information in the communicator. The languages C and FORTRAN have different approaches to using this capability:

In C: As the programmer, you normally define a struct that holds arbitrary "attribute" information. Before calling MPI_COMM_SET_ATTR, you allocate some storage for the attribute structure and then call MPI_COMM_SET_ATTR to record the address of this structure. You must make sure that the structure remains intact as long as it may be useful. As the programmer, you will also declare a variable of type "pointer to attribute structure" and pass the address of this variable when calling MPI_COMM_GET_ATTR. Both MPI_COMM_SET_ATTR and MPI_COMM_GET_ATTR take a void* parameter, but this does not imply that the same parameter is passed to either one.

In FORTRAN: MPI_COMM_SET_ATTR records an address-size integer and MPI_COMM_GET_ATTR returns the address-size integer. As the programmer, you can choose to encode all attribute information in this integer or maintain some kind of database in which the integer can index. Either of these approaches will port to other MPI implementations.

XL FORTRAN has an additional feature that will allow some of the same functions a C programmer would use. This is the POINTER type, which is described in the IBM XL FORTRAN Compiler for AIX Language Reference. Use of this feature will impact the program's portability.

Errors

Fatal errors:

MPI not initialized

MPI already finalized

Wrong keytype (MPI_ERR_ARG) attribute key is not a communicator key

Related information

MPI_ATTR_GET

MPI_COMM_DELETE_ATTR

MPI_COMM_SET_ATTR