From e649c3530c0f9b73ecf464f7b2834f4b3da004e3 Mon Sep 17 00:00:00 2001 From: mquinson Date: Mon, 7 Feb 2005 17:12:23 +0000 Subject: [PATCH] doxygenification git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@895 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/gras/datadesc.h | 233 ++++++++++++++++++++++++++++----- src/gras/DataDesc/datadesc.c | 12 +- src/gras/DataDesc/ddt_create.c | 84 ++++-------- 3 files changed, 228 insertions(+), 101 deletions(-) diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index 3550548761..7181a7c03a 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -14,64 +14,227 @@ BEGIN_DECL() -/** - * gras_datadesc_type_t: +/** @defgroup GRAS_dd Data description + * @brief Describing data to be exchanged (Communication facility) + * + * @section Overview + * + * 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 + * @ingroup GRAS_dd + * + * 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) * - * Opaque type describing a type description you don't want to open. + * 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 */ +/** @{ */ + +/** @brief Opaque type describing a type description. */ 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); + + +/** @} */ + +/** @fn gras_datadesc_type_t gras_datadesc_parse(const char *name, const char *C_statement) + * @ingroup GRAS_dd_implem + * + * Helper function doing the crude job of type parsing. + */ + +/** @name b) Automatic parsing + * @ingroup GRAS_dd + * + * 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 + * an type declaration example: \verbatim GRAS_DEFINE_TYPE(mytype,struct mytype { + int myfirstfield; + char mysecondfield; + });\endverbatim + * The type is then both copied verbatim into your source file and stored for further parsing. This allows + * you to let GRAS parse the exact version you are actually using in your program. + * You can then retrieve the corresponding type description with \ref gras_datadesc_by_symbol. + * Don't worry too much for the performances, the type is only parsed once and a binary representation + * is stored and used in any subsequent calls. + * + * If your structure contains any pointer, you have to explain GRAS the size of the pointed array. This + * can be 1 in the case of simple references, or more in the case of regular arrays. For that, use the + * \ref GRAS_ANNOTE macro within the type declaration you are passing to \ref GRAS_DEFINE_TYPE. This macro + * rewrites itself to nothing in the declaration (so they won't pollute the type definition copied verbatim + * 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. + * + * Here is an example:\verbatim GRAS_DEFINE_TYPE(s_clause, + struct s_array { + int length; + int *data GRAS_ANNOTE(size,length); + struct s_array *father GRAS_ANNOTE(size,1); + } +;)\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. + * + * If you cannot express your datadescs with this mecanism, 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 + */ +/** @{ */ + + +/** @def GRAS_DEFINE_TYPE + * @hideinitializer + * @brief Automatically parse C code + */ + + +#define GRAS_DEFINE_TYPE(name,def) \ + static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def + +/** @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_parse(#name, \ + _gras_this_type_symbol_does_not_exist__##name) \ + ) + +/** @def GRAS_ANNOTE + * @brief Add an annotation to a type to be automatically parsed + */ +#define GRAS_ANNOTE(key,val) + +/*@}*/ + +gras_datadesc_type_t +gras_datadesc_parse(const char *name, const char *C_statement); + +/** @name c) Simple manual definitions + * @ingroup GRAS_dd + * + * Here are the functions to use if you want to declare your description manually. + * The function names should be self-explanatory in most cases. + * + * You can add callbacks to the datatypes doing any kind of action you may want. Usually, + * pre-send callbacks are used to prepare the type expedition while post-receive callbacks + * are used to fix any issue after the receive. + * + * 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. + * + * If your types may contain pointer cycle, you must specify it to GRAS using the @ref gras_datadesc_cycle_set. + * + * Example:\verbatim + typedef struct { + unsigned char c1; + unsigned long int l1; + unsigned char c2; + unsigned long int l2; + } mystruct; + [...] + my_type=gras_datadesc_struct("mystruct"); + gras_datadesc_struct_append(my_type,"c1", gras_datadesc_by_name("unsigned char")); + gras_datadesc_struct_append(my_type,"l1", gras_datadesc_by_name("unsigned long")); + gras_datadesc_struct_append(my_type,"c2", gras_datadesc_by_name("unsigned char")); + gras_datadesc_struct_append(my_type,"l2", gras_datadesc_by_name("unsigned long int")); + gras_datadesc_struct_close(my_type); + + my_type=gras_datadesc_ref("mystruct*", gras_datadesc_by_name("mystruct")); + + [Use my_type to send pointers to mystruct data]\endverbatim + */ +/*@{*/ + + +/** \brief Opaque type describing a type description callback persistant state. */ 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); +/** \brief Prototype of type callbacks returning an int. */ typedef int (*gras_datadesc_type_cb_int_t)(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); -/*********************************************** - **** Search and retrieve declared datatype **** - ***********************************************/ -gras_datadesc_type_t gras_datadesc_by_name(const char *name); /****************************************** **** Declare datadescription yourself **** ******************************************/ +/** \brief Declare a new structure description */ gras_datadesc_type_t gras_datadesc_struct(const char *name); +/** \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); + +/** \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_type_t 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_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); @@ -79,32 +242,46 @@ gras_datadesc_type_t * Change stuff within datadescs * *********************************/ +/** \brief Specify that this type may contain cycles */ 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); - +/** \brief Add a pre-send callback to this datadesc. */ 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, 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, 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, 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, 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); +/** \brief Returns the identifier of a datadescription */ int gras_datadesc_get_id(gras_datadesc_type_t ddt); -/******************************************************** - * Advanced data describing: callback persistent states * - ********************************************************/ -/* simple one: push/pop sizes of arrays */ +/*@}*/ + +/** @name Callback Persistant State: Simple push/pop mecanism + * @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. + */ +/*@{*/ + void gras_cbps_i_push(gras_cbps_t ps, int val); int @@ -117,8 +294,17 @@ void gras_datadesc_cb_push_lint(gras_cbps_t vars, void *data); void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data); +/*@}*/ + +/** @name Callback Persistant State: Full featured mecanism + * @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. + */ + +/*@{*/ -/* complex one: complete variable environment support */ xbt_error_t gras_cbps_v_pop (gras_cbps_t ps, const char *name, @@ -145,7 +331,7 @@ gras_cbps_block_begin(gras_cbps_t ps); void gras_cbps_block_end(gras_cbps_t ps); - +/* @} */ /******************************* @@ -153,25 +339,9 @@ gras_cbps_block_end(gras_cbps_t ps); *******************************/ int gras_arch_selfid(void); /* ID of this arch */ -/**************************** - **** Parse C statements **** - ****************************/ -gras_datadesc_type_t -gras_datadesc_parse(const char *name, - const char *Cdefinition); -#define GRAS_DEFINE_TYPE(name,def) \ - static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def -#define GRAS_ANNOTE(key,val) - -#define gras_datadesc_by_symbol(name) \ - (gras_datadesc_by_name(#name) ? \ - gras_datadesc_by_name(#name) : \ - gras_datadesc_parse(#name, \ - _gras_this_type_symbol_does_not_exist__##name) \ - ) /***************************** - **** NWS datadescription **** + **** NWS datadescription * FIXME: obsolete? *****************************/ /** @@ -220,6 +390,7 @@ gras_datadesc_import_nws(const char *name, unsigned long howmany, /* OUT */ gras_datadesc_type_t *dst); + END_DECL() #endif /* GRAS_DATADESC_H */ diff --git a/src/gras/DataDesc/datadesc.c b/src/gras/DataDesc/datadesc.c index 6cb43be1a3..052790b95e 100644 --- a/src/gras/DataDesc/datadesc.c +++ b/src/gras/DataDesc/datadesc.c @@ -126,20 +126,12 @@ gras_datadesc_exit(void) { DEBUG0("Exited DataDesc"); } -/** - * gras_datadesc_get_name: - * - * Returns the name of a datadescription (to ease the debug) - */ +/** This is mainly to debug */ char * gras_datadesc_get_name(gras_datadesc_type_t ddt) { return ddt->name; } -/** - * gras_datadesc_get_id: - * - * Returns the name of a datadescription (to ease the debug) - */ +/** This is mainly to debug */ int gras_datadesc_get_id(gras_datadesc_type_t ddt) { return ddt->code; diff --git a/src/gras/DataDesc/ddt_create.c b/src/gras/DataDesc/ddt_create.c index 408ef38a5d..ebb8df9ea1 100644 --- a/src/gras/DataDesc/ddt_create.c +++ b/src/gras/DataDesc/ddt_create.c @@ -44,9 +44,7 @@ static gras_datadesc_type_t gras_ddt_new(const char *name) { } /** - * gras_datadesc_by_name: - * - * Retrieve a type from its name + * This returns NULL when no type of this name can be found */ gras_datadesc_type_t gras_datadesc_by_name(const char *name) { @@ -64,8 +62,6 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name) { } /** - * gras_datadesc_by_id: - * * Retrieve a type from its code */ xbt_error_t gras_datadesc_by_id(long int code, @@ -76,8 +72,6 @@ xbt_error_t gras_datadesc_by_id(long int code, } /** - * gras_datadesc_scalar: - * * Create a new scalar and give a pointer to it */ gras_datadesc_type_t @@ -117,11 +111,7 @@ gras_datadesc_type_t } -/** - * gras_dd_cat_field_free: - * - * Frees one struct or union field - */ +/** Frees one struct or union field */ void gras_dd_cat_field_free(void *f) { gras_dd_cat_field_t field = *(gras_dd_cat_field_t *)f; XBT_IN; @@ -133,11 +123,7 @@ void gras_dd_cat_field_free(void *f) { XBT_OUT; } -/** - * gras_datadesc_struct: - * - * Create a new struct and give a pointer to it - */ +/** Create a new struct and give a pointer to it */ gras_datadesc_type_t gras_datadesc_struct(const char *name) { @@ -169,11 +155,7 @@ gras_datadesc_type_t return res; } -/** - * gras_datadesc_struct_append: - * - * Append a field to the struct - */ +/** Append a field to the struct */ void gras_datadesc_struct_append(gras_datadesc_type_t struct_type, const char *name, @@ -235,6 +217,8 @@ gras_datadesc_struct_append(gras_datadesc_type_t struct_type, XBT_OUT; } +/** No new field can be added afterward, and it is mandatory to close the structure before using it. + */ void gras_datadesc_struct_close(gras_datadesc_type_t struct_type) { XBT_IN; @@ -249,7 +233,7 @@ gras_datadesc_struct_close(gras_datadesc_type_t struct_type) { /** * gras_datadesc_cycle_set: * - * Tell GRAS that the pointers of the type described by @ddt may present + * Tell GRAS that the pointers of the type described by ddt may present * some loop, and that the cycle detection mecanism is needed. * * Note that setting this option when not needed have a rather bad effect @@ -259,10 +243,11 @@ void gras_datadesc_cycle_set(gras_datadesc_type_t ddt) { ddt->cycle = 1; } + /** * gras_datadesc_cycle_unset: * - * Tell GRAS that the pointers of the type described by @ddt do not present + * Tell GRAS that the pointers of the type described by ddt do not present * any loop and that cycle detection mecanism are not needed. * (default) */ @@ -357,15 +342,13 @@ gras_datadesc_union_append(gras_datadesc_type_t union_type, } } + +/** No new field can be added afterward, and it is mandatory to close the union before using it.*/ void gras_datadesc_union_close(gras_datadesc_type_t union_type) { union_type->category.union_data.closed = 1; } -/** - * gras_datadesc_ref: - * - * Create a new ref to a fixed type and give a pointer to it - */ + gras_datadesc_type_t gras_datadesc_ref(const char *name, gras_datadesc_type_t referenced_type) { @@ -404,9 +387,9 @@ gras_datadesc_type_t return res; } /** - * gras_datadesc_ref_generic: - * - * Create a new ref to a type given at use time, and give a pointer to it + * The callback passed in argument is to be used to select which type is currently used. + * So, when GRAS wants to send a generic reference, it passes the current data to the selector + * callback and expects it to return the type description to use. */ gras_datadesc_type_t gras_datadesc_ref_generic(const char *name, @@ -446,9 +429,7 @@ gras_datadesc_type_t return res; } -/** - * gras_datadesc_array_fixed: - * +/* * Create a new array and give a pointer to it */ gras_datadesc_type_t @@ -491,9 +472,7 @@ gras_datadesc_type_t return res; } -/** - * gras_datadesc_array_dyn: - * +/* * Create a new array and give a pointer to it */ gras_datadesc_type_t @@ -542,8 +521,6 @@ gras_datadesc_type_t } /** - * gras_datadesc_ref_pop_arr: - * * Most of the time, you want to include a reference in your structure which * is a pointer to a dynamic array whose size is fixed by another field of * your structure. @@ -591,9 +568,6 @@ gras_datadesc_import_nws(const char *name, } /** - * gras_datadesc_cb_send: - * - * Add a pre-send callback to this datadesc. * (useful to push the sizes of the upcoming arrays, for example) */ void gras_datadesc_cb_send (gras_datadesc_type_t type, @@ -601,16 +575,13 @@ void gras_datadesc_cb_send (gras_datadesc_type_t type, type->send = send; } /** - * gras_datadesc_cb_recv: - * - * Add a post-receive callback to this datadesc. * (useful to put the function pointers to the rigth value, for example) */ void gras_datadesc_cb_recv(gras_datadesc_type_t type, gras_datadesc_type_cb_void_t recv) { type->recv = recv; } -/** +/* * gras_dd_find_field: * * Returns the type descriptor of the given field. Abort on error. @@ -642,9 +613,7 @@ static gras_datadesc_type_t } /** - * gras_datadesc_cb_field_send: - * - * Add a pre-send callback to the given field of the datadesc (which must be a struct or union). + * The given datadesc must be a struct or union (abort if not). * (useful to push the sizes of the upcoming arrays, for example) */ void gras_datadesc_cb_field_send (gras_datadesc_type_t type, @@ -656,10 +625,9 @@ void gras_datadesc_cb_field_send (gras_datadesc_type_t type, } /** - * gras_datadesc_cb_field_push: - * - * Add a pre-send callback to the given field resulting in its value to be pushed to - * the stack of sizes. It must be a int, unsigned int, long int or unsigned long int. + * The value, which must be an int, unsigned int, long int or unsigned long int + * is pushed to the stacks of sizes and can then be retrieved with + * \ref gras_datadesc_ref_pop_arr or directly with \ref gras_cbps_i_pop. */ void gras_datadesc_cb_field_push (gras_datadesc_type_t type, const char *field_name) { @@ -680,9 +648,7 @@ void gras_datadesc_cb_field_push (gras_datadesc_type_t type, } } /** - * gras_datadesc_cb_field_recv: - * - * Add a post-receive callback to the given field of the datadesc (which must be a struct or union). + * The given datadesc must be a struct or union (abort if not). * (useful to put the function pointers to the right value, for example) */ void gras_datadesc_cb_field_recv(gras_datadesc_type_t type, @@ -693,9 +659,7 @@ void gras_datadesc_cb_field_recv(gras_datadesc_type_t type, sub_type->recv = recv; } -/** - * gras_datadesc_free: - * +/* * Free a datadesc. Should only be called at xbt_exit. */ void gras_datadesc_free(gras_datadesc_type_t *type) { -- 2.20.1