As the previous examples showed, a communicator provides a ``scope'' for
collective invocations. The communicator, which is passed as parameter
to the call, specifies the group of processes that participate in the call and
provide a private communication domain for communications within the callee
body. In addition, it may carry information about the logical topology of the
executing processes. It is often useful to attach additional persistent values
to this scope; e.g., initialization parameters for a library, or additional
communicators to provide a separate, private communication domain.

MPI provides a caching facility that allows an application to
attach arbitrary pieces of information, called attributes, to
attribute
both intra- and intercommunicators. More precisely, the caching
facility allows a portable library to do the following:

o Pass information between calla by associating it with an MPI
intra-or intra-communicator,
o quickly retrieve that information, and
o be guaranteed that out-of-date information is never retrieved,
even if the communicator is freed and its handle subequently reused
by MPI.

Each attribute is associated with a key.
keyattribute, key
To provide safety, MPI internally generates key values.
MPI functions are provided which allow the user to allocate and
deallocate
key values (MPI_KEYVAL_CREATE and MPI_KEYVAL_FREE).
Once a key is allocated by a
process, it can be used to attach one attribute to any communicator
defined
at that process. Thus, the allocation of a key can be thought of as creating an
empty box at each current or future communicator object at that process; this
box has a lock that matches the allocated key. (The box is ``virtual'': one
need not allocate any actual space before an attempt is made to store something
in the box.)

Once the key is allocated, the user can set or access attributes
associated with this key.
The MPI call MPI_ATTR_PUT can be used to set an
attribute. This call
stores an attribute, or replaces an attribute in one box: the box attached
with the specified communicator with a lock that matches the specified key.

The
call MPI_ATTR_GET can be used to access the attribute value
associated with a given key and communicator. I.e., it allows one to access the
content of the box attached with the specified communicator, that has a lock
that matches the specified key. This call is valid even if the box is
empty, e.g., if the attribute was never set. In such case, a special
``empty'' value is returned.

Finally, the call MPI_ATTR_DELETE allows one to delete an
attribute. I.e., it allows one to empty the box attached with the
specified communicator with a lock that matches the specified key.

To be general, the
attribute mechanism must be able to store arbitrary user information.
On the other hand, attributes must be of a fixed, predefined type, both in
Fortran and C - the type specified by the MPI functions that access or
update attributes. Attributes are defined in C to be of type void *.
Generally, such an attribute will be a pointer to a user-defined data structure or
a handle to an MPI opaque object. In Fortran, attributes are of type
INTEGER. These can be handles to opaque MPI objects or indices to
user-defined tables.

An attribute, from the MPI viewpoint, is a pointer or an integer. An attribute,
from the application viewpoint, may contain arbitrary information that
is attached to
the ``MPI attribute''.
attribute
User-defined attributes are ``copied'' when a new communicator is created by
a call to MPI_COMM_DUP; they are ``deleted'' when a communicator
is deallocated by a call to MPI_COMM_FREE.
Because of the arbitrary nature of the information that is copied or
deleted, the user has to specify the semantics of
attribute copying or deletion.
The user does so
by providing copy
and delete callback functions when the attribute key is allocated (by a call to
MPI_KEYVAL_CREATE). Predefined, default copy and delete callback
functions are available.
callback function

All attribute manipulation functions are local and require no
communication. Two communicator objects at two different processes that
represent the same communication domain may have a different set of attribute
keys and different attribute values associated with them.

MPI reserves a set of predefined key values in order to associate
with MPI_COMM_WORLD information about the execution environment, at
MPI initialization time. These attribute keys are discussed in
Chapter . These keys cannot be deallocated and the
associated attributes cannot be updated by the user. Otherwise, they behave
like user-defined attributes.