MPI_ATTR_GET, MPI_Attr_get

Purpose

Retrieves an attribute value from a communicator.

C synopsis

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

FORTRAN synopsis

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

Parameters

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

keyval
     is the key value (integer) (IN)

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

flag
     is true if an attribute value was extracted and false if no attribute
     is associated with the key. (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_ATTR_GET does not interoperate with MPI_COMM_GET_ATTR. 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_ATTR_GET and MPI_ATTR_PUT 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_ATTR_PUT, you allocate some
storage for the attribute structure and then call MPI_ATTR_PUT 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_ATTR_GET. Both MPI_ATTR_PUT
and MPI_ATTR_GET take a void* parameter, but this does not imply that the
same parameter is passed to either one.

In FORTRAN: MPI_ATTR_PUT records an INTEGER*4 and MPI_ATTR_GET returns the
INTEGER*4. 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

Invalid communicator

Invalid keyval
     keyval is undefined

MPI not initialized

MPI already finalized

Related information

     MPI_ATTR_PUT