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 ); 

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)

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.

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.

ERRORS

All MPI routines except for MPI_Wtime and MPI_Wtick return an error value. The the current MPI error handler is invoked if this 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.

MPI_SUCCESS - No error;

MPI_ERR_ARG - Invalid pointer;

MPI_ERR_INTERN - Out of memory.

SEE ALSO

MPI_DUP_FN (3) MPI_NULL_COPY_FN (3) MPI_NULL_DELETE_FN (3) MPI_Keyval_free (3) MPI_Attr_put (3) MPI_Attr_get (3) MPI_Attr_delete (3)

• Lockless
• MPI Documentation
• MPI_Keyval_create