MPI_ATTR_PUT, MPI_Attr_put

Purpose

Stores an attribute value in a communicator.

C synopsis

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

FORTRAN synopsis

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

Parameters

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

keyval
     is the key value as returned by MPI_KEYVAL_CREATE (integer) (IN)

attribute_val
     is the attribute value (IN)

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

Description

This subroutine stores the attribute value for retrieval by MPI_ATTR_GET.
Any previous value is deleted with the attribute delete_fn being called and
the new value is stored. If there is no key with value keyval, the call is
erroneous.

Notes

MPI_COMM_SET_ATTR supersedes MPI_ATTR_PUT.

MPI_ATTR_PUT does not interoperate with MPI_COMM_SET_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_PUT and MPI_ATTR_GET 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

A delete_fn did not return MPI_SUCCESS

Invalid communicator

Invalid keyval
     keyval is undefined

Predefined keyval
     cannot modify predefined attributes

MPI not initialized

MPI already finalized

Related information

     MPI_COMM_COPY_ATTR_FUNCTION
     MPI_COMM_CREATE_KEYVAL
     MPI_COMM_DELETE_ATTR
     MPI_COMM_DELETE_ATTR_FUNCTION
     MPI_COMM_GET_ATTR