MPI Subroutine Reference

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

MPI_COMM_FREE