/*
* Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
* University Research and Technology
* Corporation. All rights reserved.
* Copyright (c) 2004-2005 The University of Tennessee and The University
* of Tennessee Research Foundation. All rights
* reserved.
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
* University of Stuttgart. All rights reserved.
* Copyright (c) 2004-2005 The Regents of the University of California.
* All rights reserved.
* Copyright (c) 2007 Cisco Systems, Inc. All rights reserved.
* $COPYRIGHT$
*
* Additional copyrights may follow
*
* $HEADER$
*/
/** @file
*
* Implementation for taking care of the attribute that can hang off a comm,
* win or datatype.
*/
#ifndef OMPI_ATTRIBUTE_H
#define OMPI_ATTRIBUTE_H
#include <string.h>
#include "mpi.h"
#include "ompi_config.h"
#include "ompi/constants.h"
#include "opal/class/opal_object.h"
#include "opal/class/opal_hash_table.h"
#define ATTR_HASH_SIZE 10
/*
* Flags for keyvals
*/
#define OMPI_KEYVAL_PREDEFINED 0x0001
#define OMPI_KEYVAL_F77 0x0002
#define OMPI_KEYVAL_F77_MPI1 0x0004
BEGIN_C_DECLS
enum ompi_attribute_type_t {
UNUSED_ATTR = 0, /**< Make the compilers happy when we have to construct
* an attribute */
COMM_ATTR, /**< The attribute belongs to a comm object. Starts
* with 1 so that we can have it initialized to 0
* using memset in the constructor */
TYPE_ATTR, /**< The attribute belongs to datatype object */
WIN_ATTR /**< The attribute belongs to a win object */
};
typedef enum ompi_attribute_type_t ompi_attribute_type_t;
/* Old-style MPI-1 Fortran function pointer declarations for copy and
delete. These will only be used here and not in the front end
functions. */
typedef void (ompi_mpi1_fortran_copy_attr_function)(MPI_Fint *oldobj,
MPI_Fint *keyval,
MPI_Fint *extra_state,
MPI_Fint *attr_in,
MPI_Fint *attr_out,
ompi_fortran_logical_t *flag,
MPI_Fint *ierr);
typedef void (ompi_mpi1_fortran_delete_attr_function)(MPI_Fint *obj,
MPI_Fint *keyval,
MPI_Fint *attr_in,
MPI_Fint *extra_state,
MPI_Fint *ierr);
/* New-style MPI-2 Fortran function pointer declarations for copy and
delete. These will only be used here and not in the front end
functions. */
typedef void (ompi_mpi2_fortran_copy_attr_function)(MPI_Fint *oldobj,
MPI_Fint *keyval,
void *extra_state,
void *attr_in,
void *attr_out,
ompi_fortran_logical_t *flag,
MPI_Fint *ierr);
typedef void (ompi_mpi2_fortran_delete_attr_function)(MPI_Fint *obj,
MPI_Fint *keyval,
void *attr_in,
void *extra_state,
MPI_Fint *ierr);
/*
* Internally the copy function for all kinds of MPI objects has one more
* argument, the pointer to the new object. Therefore, we can do on the
* flight modifications of the new communicator based on attributes stored
* on the main communicator.
*/
typedef int (MPI_Comm_internal_copy_attr_function)(MPI_Comm, int, void *,
void *, void *, int *,
MPI_Comm);
typedef int (MPI_Type_internal_copy_attr_function)(MPI_Datatype, int, void *,
void *, void *, int *,
MPI_Datatype);
typedef int (MPI_Win_internal_copy_attr_function)(MPI_Win, int, void *,
void *, void *, int *,
MPI_Win);
typedef void (ompi_attribute_keyval_destructor_fn_t)(int);
/* Union to take care of proper casting of the function pointers
passed from the front end functions depending on the type. This
will avoid casting function pointers to void* */
union ompi_attribute_fn_ptr_union_t {
MPI_Comm_delete_attr_function *attr_communicator_delete_fn;
MPI_Type_delete_attr_function *attr_datatype_delete_fn;
MPI_Win_delete_attr_function *attr_win_delete_fn;
MPI_Comm_internal_copy_attr_function *attr_communicator_copy_fn;
MPI_Type_internal_copy_attr_function *attr_datatype_copy_fn;
MPI_Win_internal_copy_attr_function *attr_win_copy_fn;
/* For Fortran old MPI-1 callback functions */
ompi_mpi1_fortran_delete_attr_function *attr_mpi1_fortran_delete_fn;
ompi_mpi1_fortran_copy_attr_function *attr_mpi1_fortran_copy_fn;
/* For Fortran new MPI-2 callback functions */
ompi_mpi2_fortran_delete_attr_function *attr_mpi2_fortran_delete_fn;
ompi_mpi2_fortran_copy_attr_function *attr_mpi2_fortran_copy_fn;
};
typedef union ompi_attribute_fn_ptr_union_t ompi_attribute_fn_ptr_union_t;
/**
* Union to help convert between Fortran attributes (which must be
* stored by value) and C pointers (which is the back-end storage of
* all attributes).
*/
union ompi_attribute_fortran_ptr_t {
void *c_ptr;
MPI_Fint f_integer;
MPI_Aint f_address;
};
/**
* Convenience typedef
*/
typedef union ompi_attribute_fortran_ptr_t ompi_attribute_fortran_ptr_t;
struct ompi_attribute_keyval_t {
opal_object_t super;
ompi_attribute_type_t attr_type; /**< One of COMM/WIN/DTYPE. This
will be used to cast the
copy/delete attribute functions
properly and error checking */
int attr_flag; /**< flag field: contains "OMPI_KEYVAL_PREDEFINED",
"OMPI_KEYVAL_F77" */
ompi_attribute_fn_ptr_union_t copy_attr_fn; /**< Copy function for the
attribute */
ompi_attribute_fn_ptr_union_t delete_attr_fn; /**< Delete function for the
attribute */
ompi_attribute_fortran_ptr_t extra_state; /**< Extra state of the attribute */
int key; /**< Keep a track of which key this item belongs to, so that
the key can be deleted when this object is destroyed */
/** Extra state for bindings to hang data on. If non-NULL, will be
freed by the C base when the keyval is destroyed. */
void *bindings_extra_state;
};
typedef struct ompi_attribute_keyval_t ompi_attribute_keyval_t;
/* Functions */
/**
* Convenient way to initialize the attribute hash table per MPI-Object
*/
static inline
int ompi_attr_hash_init(opal_hash_table_t **hash)
{
*hash = OBJ_NEW(opal_hash_table_t);
if (NULL == *hash) {
fprintf(stderr, "Error while creating the local attribute list\n");
return OMPI_ERR_OUT_OF_RESOURCE;
}
if (OMPI_SUCCESS != opal_hash_table_init(*hash, ATTR_HASH_SIZE)) {
return OMPI_ERR_OUT_OF_RESOURCE;
}
return MPI_SUCCESS;
}
/**
* Initialize the main attribute hash that stores the keyvals and meta data
*
* @return OMPI return code
*/
int ompi_attr_init(void);
/**
* Destroy the main attribute hash that stores the keyvals and meta data
*/
int ompi_attr_finalize(void);
/**
* Create a new key for use by attribute of Comm/Win/Datatype
*
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param copy_attr_fn Union variable containing the function pointer
* to be used in order to copy the attribute (IN)
* @param delete_attr_fn Function pointer to be used for deleting the
* attribute (IN)
* @param key The newly created key is returned here (OUT)
* @param extra_state Extra state to hang off/do some special things (IN)
* @param flags Flags for the key -- flags contain OMPI_KEYVAL_F77,
* OMPI_KEYVAL_PREDEFINED
* @param bindings_extra_state Extra state that, if non-NULL, will
* automatically be free()'ed by the C base when
* the keyval is destroyed.
*
* NOTE: I have taken the assumption that user cannot modify/delete
* any predefined keys or the attributes attached. To accomplish this,
* all MPI* calls will have OMPI_KEYVAL_PREDEFINED set as 0. MPI
* implementors who will need to play with the predefined keys and
* attributes would call the ompi* functions here and not the MPI*
* functions, with OMPI_KEYVAL_PREDEFINED set to 1.
* END OF NOTE
*
* NOTE: For the function pointers, you need to create a variable of the
* union type "ompi_attribute_fn_ptr_union_t" and assign the proper field.
* to be passed into this function
* END OF NOTE
*
* @return OMPI return code
*
*/
OMPI_DECLSPEC int ompi_attr_create_keyval(ompi_attribute_type_t type,
ompi_attribute_fn_ptr_union_t copy_attr_fn,
ompi_attribute_fn_ptr_union_t delete_attr_fn,
int *key, void *extra_state, int flags,
void *bindings_extra_state);
/**
* Same as ompi_attr_create_keyval, but extra_state is a Fortran default integer.
*/
OMPI_DECLSPEC int ompi_attr_create_keyval_fint(ompi_attribute_type_t type,
ompi_attribute_fn_ptr_union_t copy_attr_fn,
ompi_attribute_fn_ptr_union_t delete_attr_fn,
int *key, MPI_Fint extra_state, int flags,
void *bindings_extra_state);
/**
* Same as ompi_attr_create_keyval, but extra_state is a Fortran address integer.
*/
OMPI_DECLSPEC int ompi_attr_create_keyval_aint(ompi_attribute_type_t type,
ompi_attribute_fn_ptr_union_t copy_attr_fn,
ompi_attribute_fn_ptr_union_t delete_attr_fn,
int *key, MPI_Aint extra_state, int flags,
void *bindings_extra_state);
/**
* Free an attribute keyval
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param key key, which is set to MPI_KEY_INVALID (IN/OUT)
* @return OMPI error code
*/
int ompi_attr_free_keyval(ompi_attribute_type_t type, int *key,
bool predefined);
/**
* Set an attribute on the comm/win/datatype in a form valid for C.
*
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param object The actual Comm/Win/Datatype object (IN)
* @param attr_hash The attribute hash table hanging on the object(IN/OUT)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (IN)
* @param predefined Whether the key is predefined or not 0/1 (IN)
* @return OMPI error code
*
* If (*attr_hash) == NULL, a new hash will be created and
* initialized.
*
* All three of these functions (ompi_attr_set_c(),
* ompi_attr_set_fortran_mpi1(), and ompi_attr_set_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
int ompi_attr_set_c(ompi_attribute_type_t type, void *object,
opal_hash_table_t **attr_hash,
int key, void *attribute, bool predefined);
/**
* Set an attribute on the comm/win/datatype in a form valid for
* Fortran MPI-1.
*
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param object The actual Comm/Win/Datatype object (IN)
* @param attr_hash The attribute hash table hanging on the object(IN/OUT)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (IN)
* @param predefined Whether the key is predefined or not 0/1 (IN)
* @return OMPI error code
*
* If (*attr_hash) == NULL, a new hash will be created and
* initialized.
*
* All three of these functions (ompi_attr_set_c(),
* ompi_attr_set_fortran_mpi1(), and ompi_attr_set_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
OMPI_DECLSPEC int ompi_attr_set_fortran_mpi1(ompi_attribute_type_t type, void *object,
opal_hash_table_t **attr_hash,
int key, MPI_Fint attribute,
bool predefined);
/**
* Set an attribute on the comm/win/datatype in a form valid for
* Fortran MPI-2.
*
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param object The actual Comm/Win/Datatype object (IN)
* @param attr_hash The attribute hash table hanging on the object(IN/OUT)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (IN)
* @param predefined Whether the key is predefined or not 0/1 (IN)
* @return OMPI error code
*
* If (*attr_hash) == NULL, a new hash will be created and
* initialized.
*
* All three of these functions (ompi_attr_set_c(),
* ompi_attr_set_fortran_mpi1(), and ompi_attr_set_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
OMPI_DECLSPEC int ompi_attr_set_fortran_mpi2(ompi_attribute_type_t type, void *object,
opal_hash_table_t **attr_hash,
int key, MPI_Aint attribute,
bool predefined);
/**
* Get an attribute on the comm/win/datatype in a form valid for C.
*
* @param attr_hash The attribute hash table hanging on the object(IN)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (OUT)
* @param flag Flag whether an attribute is associated
* with the key (OUT)
* @return OMPI error code
*
* All three of these functions (ompi_attr_get_c(),
* ompi_attr_get_fortran_mpi1(), and ompi_attr_get_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
int ompi_attr_get_c(opal_hash_table_t *attr_hash, int key,
void **attribute, int *flag);
/**
* Get an attribute on the comm/win/datatype in a form valid for
* Fortran MPI-1.
*
* @param attr_hash The attribute hash table hanging on the object(IN)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (OUT)
* @param flag Flag whether an attribute is associated
* with the key (OUT)
* @return OMPI error code
*
* All three of these functions (ompi_attr_get_c(),
* ompi_attr_get_fortran_mpi1(), and ompi_attr_get_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
OMPI_DECLSPEC int ompi_attr_get_fortran_mpi1(opal_hash_table_t *attr_hash, int key,
MPI_Fint *attribute, int *flag);
/**
* Get an attribute on the comm/win/datatype in a form valid for
* Fortran MPI-2.
*
* @param attr_hash The attribute hash table hanging on the object(IN)
* @param key Key val for the attribute (IN)
* @param attribute The actual attribute pointer (OUT)
* @param flag Flag whether an attribute is associated
* with the key (OUT)
* @return OMPI error code
*
* All three of these functions (ompi_attr_get_c(),
* ompi_attr_get_fortran_mpi1(), and ompi_attr_get_fortran_mpi2())
* could have been combined into one function that took some kind of
* (void*) and an enum to indicate which way to translate the final
* representation, but that just seemed to make an already complicated
* situation more complicated through yet another layer of
* indirection.
*
* So yes, this is more code, but it's clearer and less error-prone
* (read: better) this way.
*/
OMPI_DECLSPEC int ompi_attr_get_fortran_mpi2(opal_hash_table_t *attr_hash, int key,
MPI_Aint *attribute, int *flag);
/**
* Delete an attribute on the comm/win/datatype
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param object The actual Comm/Win/Datatype object (IN)
* @param attr_hash The attribute hash table hanging on the object(IN)
* @param key Key val for the attribute (IN)
* @param predefined Whether the key is predefined or not 0/1 (IN)
* @return OMPI error code
*
*/
int ompi_attr_delete(ompi_attribute_type_t type, void *object,
opal_hash_table_t *attr_hash , int key,
bool predefined);
/**
* This to be used from functions like MPI_*_DUP in order to copy all
* the attributes from the old Comm/Win/Dtype object to a new
* object.
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param old_object The old COMM/WIN/DTYPE object (IN)
* @param new_object The new COMM/WIN/DTYPE object (IN)
* @param oldattr_hash The attribute hash table hanging on old object(IN)
* @param newattr_hash The attribute hash table hanging on new object(IN)
* @return OMPI error code
*
*/
int ompi_attr_copy_all(ompi_attribute_type_t type, void *old_object,
void *new_object, opal_hash_table_t *oldattr_hash,
opal_hash_table_t *newattr_hash);
/**
* This to be used to delete all the attributes from the Comm/Win/Dtype
* object in one shot
* @param type Type of attribute (COMM/WIN/DTYPE) (IN)
* @param object The COMM/WIN/DTYPE object (IN)
* @param attr_hash The attribute hash table hanging on the object(IN)
* @return OMPI error code
*
*/
int ompi_attr_delete_all(ompi_attribute_type_t type, void *object,
opal_hash_table_t *attr_hash);
/**
* \internal
*
* Create all the predefined attributes
*
* @returns OMPI_SUCCESS
*/
int ompi_attr_create_predefined(void);
/**
* \internal
*
* Free all the predefined attributes
*
* @returns OMPI_SUCCESS
*/
int ompi_attr_free_predefined(void);
END_C_DECLS
#endif /* OMPI_ATTRIBUTE_H */