MPI_KEYVAL_CREATE, MPI_Keyval_create

Purpose

Generates a new communicator attribute key.

C synopsis

#include <mpi.h>
int MPI_Keyval_create(MPI_Copy_function *copy_fn,
    MPI_Delete_function *delete_fn,int *keyval,
    void* extra_state);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_KEYVAL_CREATE(EXTERNAL COPY_FN,EXTERNAL DELETE_FN,
      INTEGER KEYVAL,INTEGER EXTRA_STATE,INTEGER IERROR)

Parameters

copy_fn
     is the copy callback function for keyval (IN)

delete_fn
     is the delete callback function for keyval (IN)

keyval
     is an integer specifying the key value for future access (OUT)

extra_state
     is the extra state for callback functions (IN)

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

Description

This subroutine generates a new attribute key. Keys are locally unique in a
task, opaque to the user, and are explicitly stored in integers. Once
allocated, keyval can be used to associate attributes and access them on
any locally-defined communicator. copy_fn is invoked when a communicator is
duplicated by MPI_COMM_DUP. It should be of type MPI_COPY_FUNCTION, which
is defined as follows:

In C:

typedef int MPI_Copy_function (MPI_Comm oldcomm,int keyval,
        void *extra_state,void *attribute_val_in,
        void *attribute_val_out,int *flag);

In FORTRAN:

SUBROUTINE COPY_FUNCTION(INTEGER OLDCOMM,INTEGER KEYVAL,
        INTEGER EXTRA_STATE,INTEGER ATTRIBUTE_VAL_IN,
        INTEGER ATTRIBUTE_VAL_OUT,LOGICAL FLAG,INTEGER IERROR)

The attribute_val_in parameter is the value of the attribute. The
attribute_val_out parameter is the address of the value, so the function
can set a new value. The attribute_val_out parameter is logically a void**,
but it is prototyped as void*, to avoid the need for complex casting.

You can use these predefined functions:

MPI_DUP_FN
     to always copy

MPI_NULL_COPY_FN
     to never copy

delete_fn is invoked when a communicator is deleted by MPI_COMM_FREE or
when a call is made to MPI_ATTR_DELETE. A call to MPI_ATTR_PUT that
overlays a previously-put attribute also causes delete_fn to be called.
It should be defined as follows:

In C:

typedef int MPI_Delete_function (MPI_Comm comm,int keyval,
        void *attribute_val, void *extra_state);

In FORTRAN:

SUBROUTINE DELETE_FUNCTION(INTEGER COMM,INTEGER KEYVAL,
        INTEGER ATTRIBUTE_VAL,INTEGER EXTRA_STATE,
        INTEGER IERROR)

You can use the predefined function MPI_NULL_DELETE_FN if no special
handling of attribute deletions is required.

In FORTRAN, the value of extra_state is recorded by MPI_KEYVAL_CREATE and
the callback functions should not attempt to modify this value.

The MPI standard requires that when copy_fn or delete_fn gives a return
code other than MPI_SUCCESS, the MPI routine in which this occurs must
fail. The standard does not suggest that the copy_fn or delete_fn return
code be used as the MPI routine's return value. The standard does require
that an MPI return code be in the range between MPI_SUCCESS and
MPI_ERR_LASTCODE. It places no range limits on copy_fn or delete_fn return
codes. For this reason, a specific error code is provided for a copy_fn
failure and another is provided for a delete_fn failure. These error codes
can be found in error class MPI_ERR_OTHER. The copy_fn return code or the
delete_fn return code is not preserved.

Notes

MPI_COMM_CREATE_KEYVAL supersedes MPI_KEYVAL_CREATE.

MPI_KEYVAL_CREATE does not interoperate with MPI_COMM_CREATE_KEYVAL. 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.

Errors

MPI not initialized

MPI already finalized

Related information

     MPI_ATTR_DELETE
     MPI_ATTR_PUT
     MPI_COMM_DUP