dss.h

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

 * buffer.
 *
 * @param size The size (in bytes) of the provided payload.
 *
 * @retval ORTE_SUCCESS The request was successfully completed
 *
 * @retval ORTE_ERROR(s) An appropriate error code indicating the
 * problem will be returned. This should be handled appropriately by
 * the caller.
 *
 * @code
 * orte_buffer_t *buffer;
 * uint8_t bytes;
 * orte_std_cntr_t size;
 *
 * buffer = OBJ_NEW(orte_buffer_t);
 * status_code = orte_dss.load(buffer, (void*)(&bytes), size);
 * @endcode
 */
typedef int (*orte_dss_load_fn_t)(orte_buffer_t *buffer,
                                  void *payload,
                                  orte_std_cntr_t size);


/**
 * DSS initialization function.
 *
 * In dynamic libraries, declared objects and functions don't get
 * loaded until called. We need to ensure that the orte_dss function
 * structure gets loaded, so we provide an "open" call that is
 * executed as part of the program startup.
 */
ORTE_DECLSPEC int orte_dss_open(void);

/**
 * DSS finalize function
 */
ORTE_DECLSPEC int orte_dss_close(void);


/**
 * Copy a data value from one location to another.
 *
 * Since registered data types can be complex structures, the system
 * needs some way to know how to copy the data from one location to
 * another (e.g., for storage in the registry). This function, which
 * can call other copy functions to build up complex data types, defines
 * the method for making a copy of the specified data type.
 *
 * @param **dest The address of a pointer into which the
 * address of the resulting data is to be stored.
 *
 * @param *src A pointer to the memory location from which the
 * data is to be copied.
 *
 * @param type The type of the data to be copied - must be one of
 * the DSS defined data types.
 *
 * @retval ORTE_SUCCESS The value was successfully copied.
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 *
 */
typedef int (*orte_dss_copy_fn_t)(void **dest, void *src, orte_data_type_t type);

/**
 * Compare two data values.
 *
 * Since registered data types can be complex structures, the system
 * needs some way to know how to compare two data values (e.g., when
 * trying to order them in some fashion). This function, which
 * can call other compare functions to build up complex data types, defines
 * the method for comparing two values of the specified data type.
 *
 * @retval -1 Indicates first value is greater than second value
 * @retval 0 Indicates two values are equal
 * @retval +1 Indicates second value is greater than first value
 */
typedef int (*orte_dss_compare_fn_t)(void *value1, void *value2,
                                     orte_data_type_t type);


/**
 * Compute size of data value.
 *
 * Since registered data types can be complex structures, the system
 * needs some way to compute its size. Some of these types, however, involve
 * variable amounts of storage (e.g., a string!). Hence, a pointer to the
 * actual object being "sized" needs to be passed as well.
 *
 * @param size Address of a size_t value where the size of the data value
 * (in bytes) will be stored - set to zero in event of error.
 *
 * @param *src A pointer to the memory location of the data object. It is okay
 * for this to be NULL - if NULL, the function must return the size of the object
 * itself, not including any data contained in its fields.
 *
 * @param type The type of the data value - must be one of
 * the DSS defined data types or an error will be returned.
 *
 * @retval ORTE_SUCCESS The value was successfully copied.
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_size_fn_t)(size_t *size, void *src, orte_data_type_t type);


/**
 * Print a data value.
 *
 * Since registered data types can be complex structures, the system
 * needs some way to know how to print them (i.e., convert them to a string
 * representation).
 *
 * @retval ORTE_SUCCESS The value was successfully printed.
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_print_fn_t)(char **output, char *prefix, void *src, orte_data_type_t type);


/**
 * Print a data value to an output stream for debugging purposes
 *
 * Uses the dss.print command to obtain a string version of the data value
 * and prints it to the designated output stream.
 *
 * @retval ORTE_SUCCESS The value was successfully printed.
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_dump_fn_t)(int output_stream, void *src, orte_data_type_t type);

/**
 * Set a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can set the data value to a specific value. This
 * is the equivalent to a C++ access function.
 *
 * NOTE: this function does NOT allocate any memory. It only sets the value pointer
 * and type to the specified location and type. Use "copy" if you want dynamic allocation
 * of storage.
 *
 * @retval ORTE_SUCCESS The value was successfully stored
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_set_fn_t)(orte_data_value_t *value, void *new_value, orte_data_type_t type);

/**
 * Get a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can get the data value from within the data_value object. This
 * is the equivalent to a C++ access function.
 *
 * NOTE: this function does NOT allocate any memory. It simply points the "data" location
 * to that of the value, after ensuring that the value's type matches the specified one.
 * Use "copy" if you want dynamic allocation of memory.
 *
 * @retval ORTE_SUCCESS The value was successfully retrieved
 *
 * @retval ORTE_ERROR(s) An appropriate error code - usually caused by the specified type
 * not matching the data type within the stored object.
 */
typedef int (*orte_dss_get_fn_t)(void **data, orte_data_value_t *value, orte_data_type_t type);

/**
 * Perform an arithemetic operation on a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can manipulate the data value within the data_value object. This
 * is the equivalent to a C++ access function.
 *
 * @retval ORTE_SUCCESS The value was successfully retrieved
 *
 * @retval ORTE_ERROR(s) An appropriate error code - usually caused by the specified type
 * not matching the data type within the stored object.
 */
typedef int (*orte_dss_arith_fn_t)(orte_data_value_t *value, orte_data_value_t *operand, orte_dss_arith_op_t operation);

/**
 * Increment a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can manipulate the data value within the data_value object. This
 * is the equivalent to a C++ access function.
 *
 * @retval ORTE_SUCCESS The value was successfully retrieved
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_increment_fn_t)(orte_data_value_t *value);

/**
 * Decrement a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can manipulate the data value within the data_value object. This
 * is the equivalent to a C++ access function.
 *
 * @retval ORTE_SUCCESS The value was successfully retrieved
 *
 * @retval ORTE_ERROR(s) An appropriate error code.
 */
typedef int (*orte_dss_decrement_fn_t)(orte_data_value_t *value);

/**
 * Release the storage used by a data value
 *
 * Since the data values are stored in an opaque manner, the system needs
 * a function by which it can release the storage associated with a value
 * stored in a data value object.
 */
typedef void (*orte_dss_release_fn_t)(orte_data_value_t *value);

/**
 * Register a set of data handling functions.
 *
 *  * This function registers a set of data type functions for a specific
 * type.  An integer is returned that should be used a an argument to
 * future invocations of orte_dss.pack(), orte_dss.unpack(), orte_dss.copy(),
 * and orte_dss.compare, which
 * will trigger calls to the appropriate functions.  This
 * is most useful when extending the datatypes that the dss can
 * handle; pack and unpack functions can nest calls to orte_dss.pack()
 * / orte_dss.unpack(), so defining small pack/unpack functions can be
 * used recursively to build larger types (e.g., packing/unpacking
 * structs can use calls to orte_dss.pack()/unpack() to serialize /
 * deserialize individual members). This is likewise true for the copy
 * and compare functions.
 *
 * @param release_fn [IN] Function pointer to the release routine
 * @param pack_fn [IN] Function pointer to the pack routine
 * @param unpack_fn [IN] Function pointer to the unpack routine
 * @param copy_fn [IN] Function pointer to copy routine
 * @param compare_fn [IN] Function pointer to compare routine
 * @param size_fn [IN] Function pointer to size routine
 * @param print_fn [IN] Function pointer to print routine
 * @param structured [IN] Boolean indicator as to whether or not the data is structured. A true
 * value indicates that this data type is always passed via reference (i.e., a pointer to the
 * object is passed) as opposed to directly (e.g., the way an int32_t would appear)
 * @param name [IN] String name for this pair (mainly for debugging)
 * @param type [OUT] Type number for this registration
 *
 * @returns ORTE_SUCCESS upon success
 *
 */
typedef int (*orte_dss_register_fn_t)(orte_dss_pack_fn_t pack_fn,
                                    orte_dss_unpack_fn_t unpack_fn,
                                    orte_dss_copy_fn_t copy_fn,
                                    orte_dss_compare_fn_t compare_fn,
                                    orte_dss_size_fn_t size_fn,
                                    orte_dss_print_fn_t print_fn,
                                    orte_dss_release_fn_t release_fn,
                                    bool structured,
                                    const char *name, orte_data_type_t *type);
/*
 * This function looks up the string name corresponding to the identified
 * data type - used for debugging messages.
 */
typedef char* (*orte_dss_lookup_data_type_fn_t)(orte_data_type_t type);

/*
 * Dump the data type list - used for debugging to see what has been registered
 */
typedef void (*orte_dss_dump_data_types_fn_t)(int output);

/**
 * Base structure for the DSS
 *
 * Base module structure for the DSS - presents the required function
 * pointers to the calling interface.
 */
struct orte_dss_t {
    orte_dss_set_fn_t 				set;
    orte_dss_get_fn_t 				get;
    orte_dss_arith_fn_t 			arith;
    orte_dss_increment_fn_t 		increment;
    orte_dss_decrement_fn_t 		decrement;
    orte_dss_set_buffer_type_fn_t 	set_buffer_type;
    orte_dss_pack_fn_t 				pack;
    orte_dss_unpack_fn_t 			unpack;
    orte_dss_copy_fn_t 				copy;
    orte_dss_compare_fn_t 			compare;
    orte_dss_size_fn_t 				size;
    orte_dss_print_fn_t 			print;
    orte_dss_release_fn_t 			release;
    orte_dss_peek_next_item_fn_t 	peek;
    orte_dss_unload_fn_t 			unload;
    orte_dss_load_fn_t 				load;
    orte_dss_register_fn_t 			register_type;
    orte_dss_lookup_data_type_fn_t 	lookup_data_type;
    orte_dss_dump_data_types_fn_t 	dump_data_types;
    orte_dss_dump_fn_t				dump;
};
typedef struct orte_dss_t orte_dss_t;

ORTE_DECLSPEC extern orte_dss_t orte_dss;  /* holds dss function pointers */

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

#endif /* ORTE_DSS_H */