MPI Subroutine Reference

MPI_COMM_CREATE_KEYVAL, MPI_Comm_create_keyval

Purpose

Creates a new attribute key for a communicator.

C synopsis

#include <mpi.h>
int MPI_Comm_create_keyval (MPI_Comm_copy_attr_function *comm_copy_attr_fn,
                            MPI_Comm_delete_attr_function *comm_delete_attr_fn,
                            int *comm_keyval, void *extra_state);

C++ synopsis

#include mpi.h
int MPI::Comm::Create_keyval(MPI::Comm::Copy_attr_function* comm_copy_attr_fn,
			     MPI::Comm::Delete_attr_function* comm_delete_attr_fn,
			     void* extra_state);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_CREATE_KEYVAL(EXTERNAL COMM_COPY_ATTR_FN, EXTERNAL COMM_DELETE_ATTR_FN,
                       INTEGER COMM_KEYVAL, INTEGER EXTRA_STATE, INTEGER IERROR)

Parameters

extra_state

is the extra state for callback functions (IN)

comm_copy_attr_fn

is the copy callback function for comm_keyval (IN)

comm_delete_attr_fn

is the delete callback function for comm_keyval (IN)

comm_keyval

is the key value for future access (integer) (OUT)

IERROR

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

Description

This subroutine creates a new attribute key for a communicator and returns a handle to it in the comm_keyval argument. A key is unique in a task and is opaque to the user. Once created, a key can be used to associate an attribute with a communicator and access it within the local task.

The argument comm_copy_attr_fn can be specified as MPI_COMM_NULL_COPY_FN or MPI_COMM_DUP_FN in C, C++, or FORTRAN. The MPI_COMM_NULL_COPY_FN function returns flag = 0 and MPI_SUCCESS. MPI_COMM_DUP_FN is a simple copy function that sets flag = 1, returns the value of attribute_val_in in attribute_val_out, and returns MPI_SUCCESS.

The argument comm_delete_attr_fn can be specified as MPI_COMM_NULL_DELETE_FN in C, C++, or FORTRAN. The MPI_COMM_NULL_DELETE_FN function, which supersedes MPI_NULL_DELETE_FN, returns MPI_SUCCESS.

The C callback functions are:

typedef int MPI_Comm_copy_attr_function(MPI_Comm oldcomm, int comm_keyval,
                                        void *extra_state, void *attribute_val_in,
                                        void *attribute_val_out, int *flag);

and

typedef int MPI_Comm_delete_attr_function(MPI_Comm comm, int comm_keyval,
                                          void *attribute_val, void *extra_state);

The FORTRAN callback functions are:

SUBROUTINE COMM_COPY_ATTR_FN(OLDCOMM, COMM_KEYVAL, EXTRA_STATE,
                             ATTRIBUTE_VAL_IN, ATTRIBUTE_VAL_OUT, FLAG, IERROR)
INTEGER OLDCOMM, COMM_KEYVAL, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE, ATTRIBUTE_VAL_IN, ATTRIBUTE_VAL_OUT
LOGICAL FLAG

and

SUBROUTINE COMM_DELETE_ATTR_FN(COMM, COMM_KEYVAL, ATTRIBUTE_VAL,
                               EXTRA_STATE, IERROR)
INTEGER COMM, COMM_KEYVAL, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) ATTRIBUTE_VAL, EXTRA_STATE

The C++ callback functions are:

typedef int MPI::Comm::Copy_attr_function(const MPI::Comm& oldcomm,
int comm_keyval, void* extra_state, void* attribute_val_in,
void* attribute_val_out, bool& flag);

and

typedef int MPI::Comm::Delete_attr_function(MPI::Comm& comm, int comm_keyval,
                                            void* attribute_val, void* extra_state);

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.

Notes

MPI_COMM_CREATE_KEYVAL supersedes MPI_KEYVAL_CREATE.

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

MPI_KEYVAL_CREATE