attribute.h

MPI stands for the Message Passing Interface. Written by the MPI Forum (a large committee comprising

 * initialized.
 *
 * Note that need_lock should *always* be true when this function is
 * invoked from an top-level MPI function.  It is only false when this
 * function is invoked internally (i.e., when we already hold the
 * relevant locks, and we don't want to try to lock them again,
 * recursively).
 *
 * 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, bool need_lock);

/**
 * 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)
 * @param need_lock      Whether we need to need to lock the keyval_lock or not
 * @return OMPI error code
 *
 * If (*attr_hash) == NULL, a new hash will be created and
 * initialized.
 *
 * Note that need_lock should *always* be true when this function is
 * invoked from an top-level MPI function.  It is only false when this
 * function is invoked internally (i.e., when we already hold the
 * relevant locks, and we don't want to try to lock them again,
 * recursively).
 *
 * 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_fortran_mpi1(ompi_attribute_type_t type, void *object, 
                               opal_hash_table_t **attr_hash,
                               int key, MPI_Fint attribute, 
                               bool predefined, bool need_lock);

/**
 * 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)
 * @param need_lock      Whether we need to need to lock the keyval_lock or not
 * @return OMPI error code
 *
 * If (*attr_hash) == NULL, a new hash will be created and
 * initialized.
 *
 * Note that need_lock should *always* be true when this function is
 * invoked from an top-level MPI function.  It is only false when this
 * function is invoked internally (i.e., when we already hold the
 * relevant locks, and we don't want to try to lock them again,
 * recursively).
 *
 * 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_fortran_mpi2(ompi_attribute_type_t type, void *object, 
                               opal_hash_table_t **attr_hash,
                               int key, MPI_Aint attribute, 
                               bool predefined, bool need_lock);

/**
 * 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.
 */

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 attrhash       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_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)
 * @param need_lock      Whether we need to need to lock the keyval_lock or not
 * @return OMPI error code
 *
 * Note that need_lock should *always* be true when this function is
 * invoked from an top-level MPI function.  It is only false when this
 * function is invoked internally (i.e., when we already hold the
 * relevant locks, and we don't want to try to lock them again,
 * recursively).
 */

int ompi_attr_delete(ompi_attribute_type_t type, void *object, 
                     opal_hash_table_t *attr_hash , int key,
                     bool predefined, bool need_lock);


/** 
 * This to be used from functions like MPI_*_DUP inorder 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 attr_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 *newkeyhash);


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

struct orte_gpr_notify_data_t;
/**
 * \internal
 * Callback function to get data from registry and create predefined attributes
 *
 * @returns Nothing
 */
void ompi_attr_create_predefined_callback(
	orte_gpr_notify_data_t *data,
	void *cbdata);


#if defined(c_plusplus) || defined(__cplusplus)
}
#endif


#endif /* OMPI_ATTRIBUTE_H */