MPI_Keyval_create(3)

NAME
MPI_Keyval_create - Create a new key value with the specified copy and delete functions

SYNOPSIS
#include <mpi.h>
int MPI_Keyval_create(MPI_Copy_function *copy, MPI_Delete_function *delete, int *keyval, void *extra_state);

#include <pmpi.h>
int PMPI_Keyval_create(MPI_Copy_function *copy, MPI_Delete_function *delete, int *keyval, void *extra_state);

INCLUDE 'mpif.h'
MPI_KEYVAL_CREATE(copy, delete, keyval, extra_state, ierr)
EXTERN copy, delete
INTEGER keyval, extra_state, ierr

INPUT PARAMETERS
copy
    - copy function to call when communicators are duplicated (function pointer)
delete
    - delete function to call when communicators are freed (function pointer)
extra_state
    - user controlled extra state to be passed to copy and delete functions (void pointer in C, integer in FORTRAN)

OUTPUT PARAMETER
keyval
    - new key value (handle)

DESCRIPTION
The MPI_Keyval_create() function is used to create a keyval handle that can be used for attribute functions. The copy and delete function pointers are called whenever communicators with attributes of this new keyval are copied or freed respectively. The extra_state parameter is passed to these function pointers. It is not altered by MPI. A keyval created by this function should eventually be freed by MPI_Keyval_free(). PMPI_Keyval_create() is the profiling version of this function. In C: The form of MPI_Copy_function is
typedef int MPI_Copy_function(MPI_Comm comm, int keyval, void *extra_state, void *attr_in, void *attr_out, int *flag);

INPUT PARAMETERS
comm
    - communicator (handle)
keyval
    - key value (handle)
extra_state
    - extra user-controlled state (void pointer handle)
attr_in
    - original attribute (void pointer handle)

OUTPUT PARAMETERS
attr_out
    - new attribute (void pointer handle)
flag
    - set to 1 if attr_out is used (boolean)

COPY FUNCTIONS
The copy function should perform an operation that copies the attribute from attr_in to attr_out. Note that even though the attr_out parameter's type is void *, it should be viewed as a void **. The other type is chosen to ease use of copy functions and avoid excess type casting. This function can use extra_state and comm to determine what other operations it may need to perform in addition to a simple copy. If attr_out contains a valid new attribute, then flag should be set to 1. Otherwise, flag should be set to 0, and attr_out will be ignored. The form of MPI_Delete_function is
typedef int MPI_Delete_function(MPI_Comm comm, int keyval, void *attr, void *extra_state);

INPUT PARAMETERS
comm
    - communicator (handle)
keyval
    - key value (handle)
attr
    - attribute (void pointer handle)
extra_state
    - extra user-controlled state (void pointer handle)

DELETE FUNCTIONS
The delete function should handle any resource deallocation required by the attribute attr. The communicator, comm, keyval, and extra_state parameters are provided so that this function may determine which operations may be required. In FORTRAN: The form of MPI_Copy_function and MPI_Delete_function are the same as in C. However, the attr and extra_state parameters are Fortran INTEGERs instead of void pointers. MPI records which type of language binding was used to create the keyval and attribute, and makes sure the correct types are passed to the copy and delete functions. Thus, when mixing C and FORTRAN, be aware that the attribute functions can have a different binding than the language default.

ERRORS
All MPI routines except for MPI_Wtime and MPI_Wtick return an error code. The the current MPI error handler is invoked if the return value is not MPI_SUCCESS. The default error handler aborts, but this may be changed with by using the MPI_Errhandler_set() function. The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned instead. Note that MPI does not guarentee that an MPI program can continue past an error. In this implementation, all errors except MPI_ERR_INTERN or MPI_ERR_OTHER should always be recoverable. In C, the error code is passed as the return value. In FORTRAN, all functions have an parameter ierr which returns the error code. MPI C++ functions do not directly return an error code. However, C++ users may want to use the MPI::ERRORS_THROW_EXCEPTIONS handler. This will throw an MPI::Exception with the corresponding error code. To prevent exceptions from being raised from within C and Fortran code, they will see all error return values as MPI_ERR_PENDING when this handler is chosen. In this implementation, call MPI::throw_exception() to throw the correct exception if this occurs.
MPI_SUCCESS
    - No error;
MPI_ERR_PENDING
    - Pending exception;
MPI_ERR_ARG
    - Invalid pointer;
MPI_ERR_INTERN
    - Out of memory.

SEE ALSO
MPI_Keyval_free(3), MPI_Attr_put(3), MPI_Attr_get(3), MPI_Attr_delete(3)