X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/eed8daedf7c2d58e0db96826205f138cedb9cc5a..0bfb3cdebf6d1a0105a7a738a602015ed583a39e:/include/gras/datadesc.h diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index 3df17d1c7c..393cd4c935 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -16,12 +16,7 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_dd Data description - * @brief Describing data to be exchanged (Communication facility) - * - *
Top [\ref index]::[\ref GRAS_API] - *
Prev - *
Next [\ref GRAS_sock] - *
Down [\ref GRAS_dd_basic]
+ * @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. @@ -44,16 +39,14 @@ SG_BEGIN_DECL() /** @defgroup GRAS_dd_basic Basic operations on data descriptions * @ingroup GRAS_dd - *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] - *
Prev - *
Next [\ref GRAS_dd_auto]
+ * \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: * - char (both signed and unsigned) * - int (short, regular, long and long long, both signed and unsigned) * - float and double - * - string (which is indeed a reference to a dynamically sized array of char, strlen being used to retrive the size) + * - string (which is indeed a reference to a dynamically sized array of char, strlen being used to retrieve the size) * * Example:\verbatim gras_datadesc_type_t i = gras_datadesc_by_name("int"); gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char"); @@ -66,15 +59,14 @@ SG_BEGIN_DECL() typedef struct s_gras_datadesc_type *gras_datadesc_type_t; /** \brief Search a type description from its name */ -gras_datadesc_type_t gras_datadesc_by_name(const char *name); +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_by_name(const char *name); +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_by_name_or_null(const char *name); /* @} */ /** @defgroup GRAS_dd_auto Automatic parsing of data descriptions * @ingroup GRAS_dd - *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] - *
Prev [\ref GRAS_dd_basic] - *
Next [\ref GRAS_dd_manual]
+ * \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 @@ -113,26 +105,104 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); * 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. + * + * \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 + * + * \section gras_dd_define \#define and fixed size array + * + * If you want to exchange arrays which size is given at compilation time by a + * \#defined constant, you need to keep GRAS informed. It would be done the + * following way: + +\verbatim #define BLOCK_SIZE 32 +GRAS_DEFINE_TYPE(s_toto, +struct { + double data[BLOCK_SIZE]; +} s_toto;) + +void register_messages() { + gras_datadesc_type_t toto_type; + + gras_datadesc_set_const("BLOCK_SIZE",BLOCK_SIZE); + toto_type = gras_datadesc_by_symbol(s_toto); +}\endverbatim + * + * The form gras_datadesc_set_const("BLOCK_SIZE",BLOCK_SIZE); ensures + * that when you change the definition of the constant, GRAS keeps informed of + * the right value. Passing the numerical value of the constant as second + * argument would be a bad idea to that regard. Of course, the call to + * gras_datadesc_set_const() should come before any gras_datadesc_by_symbol() + * containing references to it. + * + * \section GRAS_dd_multidim Defining multidimentional arrays * - * \warning The mecanism for multidimensional arrays is known to be fragile and cumbersome. If you want to use it, + * 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 + * added to \a cols. So, when the structure is sent, the \a 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 retrieve 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 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 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. + * (and somehow complex) one described in the \ref GRAS_dd_cb_full. * - * \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 + * \section GRAS_dd_multifile Projects spanning over multiple files + * + * GRAS_DEFINE_TYPE declares some symbols to work, it needs some special + * care when used in several files. In such case, you want the regular type + * definition in all files, but the gras specific symbol defined in only + * one file. For example, consider the following gras project sketch. + * +\verbatim #include + +GRAS_DEFINE_TYPE(my_type,struct my_type { + int a; + int b; + double c; +}); + +int client(int argc, char *argv[]) { + ... +} + +int server(int argc, char *argv[]) { + ... +}\endverbatim + * + * If you want to split this in two files (one for each kind of processes), + * you need to put the GRAS_DEFINE_TYPE block in a separate header. But + * then you cannot include this right away in all files because the extra + * symbols would be defined in dupplicate. + * + * You thus have to decide in which file the symbols will live. In that + * file, include the header without restriction: + * +\verbatim #include "my_header.h" + +int client(int argc, char *argv[]) { + ... +}\endverbatim + + * And in the other files needing the C definitions without the extra GRAS + * symbols, declare the symbol GRAS_DEFINE_TYPE_EXTERN before: + * +\verbatim #define GRAS_DEFINE_TYPE_EXTERN +#include "my_header.h" + +int server(int argc, char *argv[]) { + ... +}\endverbatim + + * */ /** @{ */ @@ -141,14 +211,29 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); * @hideinitializer */ #define GRAS_DEFINE_TYPE(name,def) \ - static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def - + const char * _gras_this_type_symbol_does_not_exist__##name=#def; def + +#ifndef DOXYGEN_SKIP /* doxygen don't like macro fun too much */ +# ifdef GRAS_DEFINE_TYPE_EXTERN +# undef GRAS_DEFINE_TYPE +# define GRAS_DEFINE_TYPE(name,def) def +# undef GRAS_DEFINE_TYPE_EXTERN +# endif +#endif + +/** @brief if this symbol is defined, the \a GRAS_DEFINE_TYPE symbols live in another file. + * @hideinitializer + */ +#define GRAS_DEFINE_TYPE_EXTERN 1 + + + /** @brief Retrieve a datadesc which was previously parsed * @hideinitializer */ #define gras_datadesc_by_symbol(name) \ - (gras_datadesc_by_name(#name) ? \ - gras_datadesc_by_name(#name) : \ + (gras_datadesc_by_name_or_null(#name) ? \ + gras_datadesc_by_name_or_null(#name) : \ gras_datadesc_parse(#name, \ _gras_this_type_symbol_does_not_exist__##name) \ ) @@ -157,17 +242,18 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); * @brief Add an annotation to a type to be automatically parsed */ #define GRAS_ANNOTE(key,val) + +/** @brief Defines the value of a define to the datatype parsing infrastructure + */ +XBT_PUBLIC(void) gras_datadesc_set_const(const char*name, int value); /* @} */ -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_parse(const char *name, const char *C_statement); /** @defgroup GRAS_dd_manual Simple manual data description * @ingroup GRAS_dd - *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] - *
Prev [\ref GRAS_dd_auto] - *
Next [\ref GRAS_dd_cb_simple]
* * Here are the functions to use if you want to declare your description manually. * The function names should be self-explanatory in most cases. @@ -220,91 +306,92 @@ typedef gras_datadesc_type_t (*gras_datadesc_selector_t)(gras_datadesc_type_t ty **** Declare datadescription yourself **** ******************************************/ -gras_datadesc_type_t gras_datadesc_struct(const char *name); -void gras_datadesc_struct_append(gras_datadesc_type_t struct_type, +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_struct(const char *name); +XBT_PUBLIC(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); +XBT_PUBLIC(void) gras_datadesc_struct_close(gras_datadesc_type_t struct_type); -gras_datadesc_type_t gras_datadesc_union(const char *name, +XBT_PUBLIC(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, +XBT_PUBLIC(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); +XBT_PUBLIC(void) gras_datadesc_union_close(gras_datadesc_type_t union_type); -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_ref(const char *name, gras_datadesc_type_t referenced_type); -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_ref_generic(const char *name, gras_datadesc_selector_t selector); -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_array_fixed(const char *name, gras_datadesc_type_t element_type, long int fixed_size); -gras_datadesc_type_t +XBT_PUBLIC(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); -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_ref_pop_arr(gras_datadesc_type_t element_type); -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_dynar(gras_datadesc_type_t elm_t, void_f_pvoid_t *free_func); +XBT_PUBLIC(gras_datadesc_type_t) + gras_datadesc_matrix(gras_datadesc_type_t elm_t, + void_f_pvoid_t * const free_f); /********************************* * Change stuff within datadescs * *********************************/ /** \brief Specify that this type may contain cycles */ -void gras_datadesc_cycle_set(gras_datadesc_type_t type); +XBT_PUBLIC(void) gras_datadesc_cycle_set(gras_datadesc_type_t type); /** \brief Specify that this type do not contain any cycles (default) */ -void gras_datadesc_cycle_unset(gras_datadesc_type_t type); +XBT_PUBLIC(void) gras_datadesc_cycle_unset(gras_datadesc_type_t type); /** \brief Add a pre-send callback to this datadesc. */ -void gras_datadesc_cb_send (gras_datadesc_type_t type, +XBT_PUBLIC(void) gras_datadesc_cb_send (gras_datadesc_type_t type, gras_datadesc_type_cb_void_t pre); /** \brief Add a post-receive callback to this datadesc.*/ -void gras_datadesc_cb_recv(gras_datadesc_type_t type, +XBT_PUBLIC(void) gras_datadesc_cb_recv(gras_datadesc_type_t type, gras_datadesc_type_cb_void_t post); /** \brief Add a pre-send callback to the given field of the datadesc */ -void gras_datadesc_cb_field_send (gras_datadesc_type_t type, +XBT_PUBLIC(void) gras_datadesc_cb_field_send (gras_datadesc_type_t type, const char *field_name, gras_datadesc_type_cb_void_t pre); /** \brief Add a post-receive callback to the given field of the datadesc */ -void gras_datadesc_cb_field_recv(gras_datadesc_type_t type, +XBT_PUBLIC(void) gras_datadesc_cb_field_recv(gras_datadesc_type_t type, const char *field_name, gras_datadesc_type_cb_void_t post); /** \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, +XBT_PUBLIC(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, +XBT_PUBLIC(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 */ -const char * gras_datadesc_get_name(gras_datadesc_type_t ddt); +XBT_PUBLIC(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); +XBT_PUBLIC(int) gras_datadesc_get_id(gras_datadesc_type_t ddt); /* @} */ /** @defgroup GRAS_dd_cb_simple Data description with Callback Persistant State: Simple push/pop mechanism * @ingroup GRAS_dd - *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] - *
Prev [\ref GRAS_dd_manual] - *
Next [\ref GRAS_dd_cb_full]
* * 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 { @@ -345,57 +432,59 @@ gras_datadesc_struct_close(my_type); */ /* @{ */ -void +XBT_PUBLIC(void) gras_cbps_i_push(gras_cbps_t ps, int val); -int +XBT_PUBLIC(int) gras_cbps_i_pop(gras_cbps_t ps); -int gras_datadesc_cb_pop(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(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); +XBT_PUBLIC(void) gras_datadesc_cb_push_int(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(void) gras_datadesc_cb_push_uint(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(void) gras_datadesc_cb_push_lint(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(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); +XBT_PUBLIC(void) gras_datadesc_cb_push_int_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(void) gras_datadesc_cb_push_uint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(void) gras_datadesc_cb_push_lint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); +XBT_PUBLIC(void) gras_datadesc_cb_push_ulint_mult(gras_datadesc_type_t typedesc, gras_cbps_t vars, void *data); /* @} */ /** @defgroup GRAS_dd_cb_full Data description with Callback Persistant State: Full featured interface * @ingroup GRAS_dd - *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] - *
Prev [\ref GRAS_dd_cb_simple] - *
Next
* - * 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. + * 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 + * */ /* @{ */ -void gras_cbps_v_pop (gras_cbps_t ps, +XBT_PUBLIC(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, +XBT_PUBLIC(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, +XBT_PUBLIC(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, +XBT_PUBLIC(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); +XBT_PUBLIC(void) gras_cbps_block_begin(gras_cbps_t ps); +XBT_PUBLIC(void) gras_cbps_block_end(gras_cbps_t ps); /* @} */ /* @} */ @@ -404,7 +493,7 @@ void gras_cbps_block_end(gras_cbps_t ps); /******************************* **** About data convertion **** *******************************/ -int gras_arch_selfid(void); /* ID of this arch */ +XBT_PUBLIC(int) gras_arch_selfid(void); /* ID of this arch */ /***************************** @@ -451,7 +540,7 @@ typedef struct DataDescriptorStruct { sizeof(structType) - offsetof(structType, lastMember) - \ sizeof(memberType) * repetitions -gras_datadesc_type_t +XBT_PUBLIC(gras_datadesc_type_t) gras_datadesc_import_nws(const char *name, const DataDescriptor *desc, unsigned long howmany);