X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/1132c208390db403e0fe891f6ff0cda438e0023c..337c0de59186a44f7a146bc28628ee10f6e5f9ed:/include/gras/datadesc.h diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index f7ccad89ca..7ea963ead9 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -10,24 +10,36 @@ #ifndef GRAS_DATADESC_H #define GRAS_DATADESC_H -#include "xbt/misc.h" /* BEGIN_DECL */ +#include "xbt/misc.h" /* SG_BEGIN_DECL */ +#include "xbt/dynar.h" /* void_f_pvoid_t */ -BEGIN_DECL() +SG_BEGIN_DECL() -/** @defgroup GRAS_dd Data description - * @brief Describing data to be exchanged (Communication facility) - * - * @section Overview +/** @addtogroup GRAS_dd Data description + * @brief Describing data to be exchanged * * Since GRAS takes care of potential representation conversion when the platform is heterogeneous, * any data which transits on the network must be described beforehand. * * There is several possible interfaces for this, ranging from the really completely automatic parsing to - * completely manual. Let's study each of them from the simplest to the more advanced. - */ - -/** @name a) basic operations + * completely manual. Let's study each of them from the simplest to the more advanced: + * + * - Section \ref GRAS_dd_basic presents how to retrieve and use an already described type. + * - Section \ref GRAS_dd_auto shows how to get GRAS parsing your type description automagically. This + * is unfortunately not always possible (only works for some structures), but if it is for your data, + * this is definitly the way to go. + * - Section \ref GRAS_dd_manual presents how to build a description manually. This is useful when you want + * to describe an array or a pointer of pre-defined structures. + * - You sometimes need to exchange informations between descriptions at send or receive time. This is + * for example useful when your structure contains an array which size is given by another field of the + * structure. + * - Section \ref GRAS_dd_cb_simple provides a simple interface to do so, allowing to share integers stored on a stack. + * - Section \ref GRAS_dd_cb_full provides a full featured interface to do so, but it may reveal somehow difficult to use. + **/ + +/** @defgroup GRAS_dd_basic Basic operations on data descriptions * @ingroup GRAS_dd + * \htmlonly \endhtmlonly * * If you only want to send pre-existing types, simply retrieve the pre-defined description with * the \ref gras_datadesc_by_name function. Existing types entail: @@ -39,6 +51,7 @@ BEGIN_DECL() * Example:\verbatim gras_datadesc_type_t i = gras_datadesc_by_name("int"); gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char"); gras_datadesc_type_t str = gras_datadesc_by_name("string");\endverbatim + * */ /* @{ */ @@ -50,8 +63,9 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); /* @} */ -/** @name b) Automatic parsing +/** @defgroup GRAS_dd_auto Automatic parsing of data descriptions * @ingroup GRAS_dd + * \htmlonly \endhtmlonly * * If you need to declare a new datatype, this is the simplest way to describe it to GRAS. Simply * enclose its type definition into a \ref GRAS_DEFINE_TYPE macro call, and you're set. Here is @@ -72,27 +86,44 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); * into your code), and give some information to GRAS about your pointer. * GRAS_ANNOTE takes two arguments being the key name and the key value. For now, the only accepted key name - * is "size", to specify the length of the pointed array. It can either be the string "1" (without the quote) - * or the name of another field of the structure. + * is "size", to specify the length of the pointed array. It can either be: + * - the string "1" (without the quote), + * - the name of another field of the structure + * - a sort of computed expression for multidimensional arrays (see below -- pay attention to the warnings below). * * Here is an example:\verbatim GRAS_DEFINE_TYPE(s_clause, struct s_array { + struct s_array *father GRAS_ANNOTE(size,1); int length; int *data GRAS_ANNOTE(size,length); - struct s_array *father GRAS_ANNOTE(size,1); + int rows; + int cols; + int *matrix GRAS_ANNOTE(size,rows*cols); } ;)\endverbatim - * It specifies that the structure s_array contains two fields, and that the size of the array pointed - * by \a data is the \a length field, and that the \a father field is a simple reference. + * It specifies that the structure s_array contains five fields, that the \a father field is a simple reference, + * that the size of the array pointed by \a data is the \a length field, and that the \a matrix field is an array + * which size is the result of \a rows times \a cols. * - * If you cannot express your datadescs with this mecanism, you'll have to use the more advanced + * \warning The mecanism for multidimensional arrays is known to be fragile and cumbersome. If you want to use it, + * you have to understand how it is implemented: the multiplication is performed using the sizes stack. In previous example, + * a \ref gras_datadesc_cb_push_int callback is added to the \a rows field and a \ref gras_datadesc_cb_push_int_mult one is + * added to \a cols. So, when the structure is sent, the rows field push its value onto the stack, then the \a cols field + * retrieve this value from the stack, compute (and push) the multiplication value. The \a matrix field can then retrive this + * value by poping the array. There is several ways for this to go wrong: + * - if the matrix field is placed before the sizes, the right value won't get pushed into the stack soon enough. Reorder your structure fields if needed. + * - if you write GRAS_ANNOTE(size,cols*rows); in previous example (inverting rows and cols in annotation), + * \a rows will be given a \ref gras_datadesc_cb_push_int_mult. This cannot work since it will try to + * pop the value which will be pushed by \a cols afterward. + * - if you have more than one matrix in your structure, don't interleave the size. They are pushed/poped in the structure order. + * - if some of the sizes are used in more than one matrix, you cannot use this mecanism -- sorry. + * + * If you cannot express your datadescs with this mechanism, you'll have to use the more advanced * (and somehow complex) one described below. - * - * \warning Since GRAS_DEFINE_TYPE is a macro, you shouldn't put any comma in your type definition - * (comma separates macro args). - * - * For example, change \verbatim int a, b;\endverbatim to \verbatim int a; - int b:\endverbatim + * + * \warning Since GRAS_DEFINE_TYPE is a macro, you shouldn't put any comma in your type definition + * (comma separates macro args). For example, change \verbatim int a, b;\endverbatim to \verbatim int a; + int b;\endverbatim */ /** @{ */ @@ -118,12 +149,12 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); */ #define GRAS_ANNOTE(key,val) -/*@}*/ +/* @} */ gras_datadesc_type_t gras_datadesc_parse(const char *name, const char *C_statement); -/** @name c) Simple manual definitions +/** @defgroup GRAS_dd_manual Simple manual data description * @ingroup GRAS_dd * * Here are the functions to use if you want to declare your description manually. @@ -135,7 +166,7 @@ gras_datadesc_parse(const char *name, const char *C_statement); * * If your types are dynamic, you'll need to add some extra callback. For example, there is a * specific callback for the string type which is in charge of computing the length of the char - * array. This is done with the cbps mecanism, explained in next section. + * array. This is done with the cbps mechanism, explained in next section. * * If your types may contain pointer cycle, you must specify it to GRAS using the @ref gras_datadesc_cycle_set. * @@ -158,7 +189,7 @@ gras_datadesc_parse(const char *name, const char *C_statement); [Use my_type to send pointers to mystruct data]\endverbatim */ -/*@{*/ +/* @{ */ /** \brief Opaque type describing a type description callback persistant state. */ @@ -166,68 +197,54 @@ typedef struct s_gras_cbps *gras_cbps_t; /* callbacks prototypes */ /** \brief Prototype of type callbacks returning nothing. */ -typedef void (*gras_datadesc_type_cb_void_t)(gras_cbps_t vars, void *data); +typedef void (*gras_datadesc_type_cb_void_t)(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); /** \brief Prototype of type callbacks returning an int. */ -typedef int (*gras_datadesc_type_cb_int_t)(gras_cbps_t vars, void *data); +typedef int (*gras_datadesc_type_cb_int_t)(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); /** \brief Prototype of type callbacks selecting a type. */ -typedef gras_datadesc_type_t (*gras_datadesc_selector_t)(gras_cbps_t vars, void *data); +typedef gras_datadesc_type_t (*gras_datadesc_selector_t)(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); /****************************************** **** Declare datadescription yourself **** ******************************************/ -/** \brief Declare a new structure description */ gras_datadesc_type_t gras_datadesc_struct(const char *name); +void gras_datadesc_struct_append(gras_datadesc_type_t struct_type, + const char *name, + gras_datadesc_type_t field_type); +void gras_datadesc_struct_close(gras_datadesc_type_t struct_type); -/** \brief Append a new field to a structure description */ -void - gras_datadesc_struct_append(gras_datadesc_type_t struct_type, - const char *name, - gras_datadesc_type_t field_type); -/** \brief Close a structure description */ -void - gras_datadesc_struct_close(gras_datadesc_type_t struct_type); -/** \brief Declare a new union description */ -gras_datadesc_type_t - gras_datadesc_union(const char *name, - gras_datadesc_type_cb_int_t selector); -/** \brief Append a new field to an union description */ -void - gras_datadesc_union_append(gras_datadesc_type_t union_type, - const char *name, - gras_datadesc_type_t field_type); -/** \brief Close an union description */ -void - gras_datadesc_union_close(gras_datadesc_type_t union_type); +gras_datadesc_type_t gras_datadesc_union(const char *name, + gras_datadesc_type_cb_int_t selector); +void gras_datadesc_union_append(gras_datadesc_type_t union_type, + const char *name, + gras_datadesc_type_t field_type); +void gras_datadesc_union_close(gras_datadesc_type_t union_type); -/** \brief Declare a new type being a reference to the one passed in arg */ gras_datadesc_type_t - gras_datadesc_ref(const char *name, - gras_datadesc_type_t referenced_type); -/** \brief Declare a new type being a generic reference. */ + gras_datadesc_ref(const char *name, + gras_datadesc_type_t referenced_type); gras_datadesc_type_t - gras_datadesc_ref_generic(const char *name, - gras_datadesc_selector_t selector); + gras_datadesc_ref_generic(const char *name, + gras_datadesc_selector_t selector); -/** \brief Declare a new type being an array of fixed size and content */ gras_datadesc_type_t - gras_datadesc_array_fixed(const char *name, - gras_datadesc_type_t element_type, - long int fixed_size); - -/** \brief Declare a new type being an array of fixed size, but accepting several content types. */ + gras_datadesc_array_fixed(const char *name, + gras_datadesc_type_t element_type, + long int fixed_size); gras_datadesc_type_t gras_datadesc_array_dyn(const char *name, gras_datadesc_type_t element_type, gras_datadesc_type_cb_int_t dynamic_size); - -/** \brief Declare a new type being an array which size can be found with \ref gras_cbps_i_pop */ gras_datadesc_type_t gras_datadesc_ref_pop_arr(gras_datadesc_type_t element_type); +gras_datadesc_type_t + gras_datadesc_dynar(gras_datadesc_type_t elm_t, + void_f_pvoid_t *free_func); + /********************************* * Change stuff within datadescs * *********************************/ @@ -253,22 +270,27 @@ void gras_datadesc_cb_field_recv(gras_datadesc_type_t type, /** \brief Add a pre-send callback to the given field resulting in its value to be pushed */ void gras_datadesc_cb_field_push (gras_datadesc_type_t type, const char *field_name); +/** \brief Add a pre-send callback to the given field resulting in its value multiplied to any previously pushed value and then pushed back */ +void gras_datadesc_cb_field_push_multiplier (gras_datadesc_type_t type, + const char *field_name); /****************************** * Get stuff within datadescs * ******************************/ /** \brief Returns the name of a datadescription */ -char * gras_datadesc_get_name(gras_datadesc_type_t ddt); +const char * gras_datadesc_get_name(gras_datadesc_type_t ddt); /** \brief Returns the identifier of a datadescription */ int gras_datadesc_get_id(gras_datadesc_type_t ddt); -/*@}*/ +/* @} */ -/** @name Callback Persistant State: Simple push/pop mecanism +/** @defgroup GRAS_dd_cb_simple Data description with Callback Persistant State: Simple push/pop mechanism * @ingroup GRAS_dd * * Sometimes, one of the callbacks need to leave information for the next ones. If this is a simple integer (such as * an array size), you can use the functions described here. If not, you'll have to play with the complete cbps interface. + * + * \htmlonly \endhtmlonly * * Here is an example:\verbatim struct s_array { @@ -285,59 +307,86 @@ gras_datadesc_struct_append(my_type,"data", gras_datadesc_struct_close(my_type); \endverbatim + * + * The *_mult versions are intended for multi-dimensional arrays: They multiply their value to the previously pushed one + * (by another field callback) and push the result of the multiplication back. An example of use follows. Please note + * that the first field needs a regular push callback, not a multiplier one. Think of it as a stacked calculator (man dc(1)).\verbatim +struct s_matrix { + int row; + int col; + int *data; +} +[...] +my_type=gras_datadesc_struct("s_matrix"); +gras_datadesc_struct_append(my_type,"row", gras_datadesc_by_name("int")); +gras_datadesc_cb_field_send (my_type, "length", gras_datadesc_cb_push_int); +gras_datadesc_struct_append(my_type,"col", gras_datadesc_by_name("int")); +gras_datadesc_cb_field_send (my_type, "length", gras_datadesc_cb_push_int_mult); + +gras_datadesc_struct_append(my_type,"data", + gras_datadesc_array_dyn ("s_matrix::data",gras_datadesc_by_name("int"), gras_datadesc_cb_pop)); +gras_datadesc_struct_close(my_type); +\endverbatim + */ -/*@{*/ +/* @{ */ void gras_cbps_i_push(gras_cbps_t ps, int val); int gras_cbps_i_pop(gras_cbps_t ps); -int gras_datadesc_cb_pop(gras_cbps_t vars, void *data); -void gras_datadesc_cb_push_int(gras_cbps_t vars, void *data); -void gras_datadesc_cb_push_uint(gras_cbps_t vars, void *data); -void gras_datadesc_cb_push_lint(gras_cbps_t vars, void *data); -void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data); +int gras_datadesc_cb_pop(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_int(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_uint(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_lint(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_ulint(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); -/*@}*/ +void gras_datadesc_cb_push_int_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_uint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_lint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +void gras_datadesc_cb_push_ulint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); -/** @name Callback Persistant State: Full featured mecanism + +/* @} */ + +/** @defgroup GRAS_dd_cb_full Data description with Callback Persistant State: Full featured interface * @ingroup GRAS_dd * - * Sometimes, one of the callbacks need to leave information for the next ones. If the simple push/pop mecanism - * introduced in previous section isn't enough, you can always use this full featured one. + * Sometimes, one of the callbacks need to leave information for the next + * ones. If the simple push/pop mechanism introduced in previous section + * isn't enough, you can always use this full featured one. The bad point is + * that it is quite badly documented... + * + * \htmlonly \endhtmlonly + * */ -/*@{*/ - -xbt_error_t - gras_cbps_v_pop (gras_cbps_t ps, - const char *name, - /* OUT */ gras_datadesc_type_t *ddt, - /* OUT */ void **res); -xbt_error_t -gras_cbps_v_push(gras_cbps_t ps, - const char *name, - void *data, - gras_datadesc_type_t ddt); -void -gras_cbps_v_set (gras_cbps_t ps, - const char *name, - void *data, - gras_datadesc_type_t ddt); +/* @{ */ -void * -gras_cbps_v_get (gras_cbps_t ps, - const char *name, - /* OUT */ gras_datadesc_type_t *ddt); - -void -gras_cbps_block_begin(gras_cbps_t ps); -void -gras_cbps_block_end(gras_cbps_t ps); +void gras_cbps_v_pop (gras_cbps_t ps, + const char *name, + /* OUT */ gras_datadesc_type_t *ddt, + /* OUT */ void **res); +void gras_cbps_v_push(gras_cbps_t ps, + const char *name, + void *data, + gras_datadesc_type_t ddt); +void gras_cbps_v_set (gras_cbps_t ps, + const char *name, + void *data, + gras_datadesc_type_t ddt); + +void * gras_cbps_v_get (gras_cbps_t ps, + const char *name, + /* OUT */ gras_datadesc_type_t *ddt); + +void gras_cbps_block_begin(gras_cbps_t ps); +void gras_cbps_block_end(gras_cbps_t ps); /* @} */ +/* @} */ /******************************* @@ -359,15 +408,15 @@ typedef enum DataTypes; #define SIMPLE_TYPE_COUNT 9 -/*! \brief Describe a collection of data. +/** \brief Describe a collection of data. * -** A description of a collection of #type# data. #repetitions# is used only -** for arrays; it contains the number of elements. #offset# is used only for +** A description of a collection of \a type data. \a repetitions is used only +** for arrays; it contains the number of elements. \a offset is used only for ** struct members in host format; it contains the offset of the member from the ** beginning of the struct, taking into account internal padding added by the -** compiler for alignment purposes. #members#, #length#, and #tailPadding# are -** used only for STRUCT_TYPE data; the #length#-long array #members# describes -** the members of the nested struct, and #tailPadding# indicates how many +** compiler for alignment purposes. \a members, \a length, and \a tailPadding are +** used only for STRUCT_TYPE data; the \a length -long array \a members describes +** the members of the nested struct, and \a tailPadding indicates how many ** padding bytes the compiler adds to the end of the structure. */ @@ -390,13 +439,12 @@ typedef struct DataDescriptorStruct { sizeof(structType) - offsetof(structType, lastMember) - \ sizeof(memberType) * repetitions -xbt_error_t +gras_datadesc_type_t gras_datadesc_import_nws(const char *name, const DataDescriptor *desc, - unsigned long howmany, - /* OUT */ gras_datadesc_type_t *dst); + unsigned long howmany); -END_DECL() +SG_END_DECL() #endif /* GRAS_DATADESC_H */