From eed8daedf7c2d58e0db96826205f138cedb9cc5a Mon Sep 17 00:00:00 2001 From: mquinson Date: Sat, 22 Oct 2005 11:38:43 +0000 Subject: [PATCH] Documentation reorganization: no @name anymore since doxygen was buggy on it until now and now refuse to parse them. Instead split parts onto other pages; add navigation bar to fight the resulting mess git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@1789 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/gras/datadesc.h | 61 +++++++++++++++++++++++++++++----------- include/gras/emul.h | 4 +++ include/gras/messages.h | 25 ++++++++++++++-- include/gras/process.h | 4 +++ include/gras/timer.h | 4 +++ include/gras/transport.h | 38 +++++++++++++++++++++---- include/gras/virtu.h | 5 ++++ 7 files changed, 116 insertions(+), 25 deletions(-) diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index e259f446eb..3df17d1c7c 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -18,25 +18,35 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_dd Data description * @brief Describing data to be exchanged (Communication facility) * - * @section Overview + *
Top [\ref index]::[\ref GRAS_API] + *
Prev + *
Next [\ref GRAS_sock] + *
Down [\ref GRAS_dd_basic]
* * 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. + * completely manual. Let's study each of them from the simplest to the more advanced: * - * \warning At least, I would like to present those sections in the right order, but doxygen prevents me - * from doing so. There is a weird bug I fail to circumvent here. The right order is naturally: - * -# basic operations - * -# Automatic parsing - * -# Simple manual definitions - * -# Callback Persistant State: Simple push/pop mechanism - * -# Callback Persistant State: Full featured mechanism - */ -/* @{*/ - -/** @name 1. basic operations + * - 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 + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd] + *
Prev + *
Next [\ref GRAS_dd_auto]
* * 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: @@ -48,6 +58,7 @@ SG_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 + * */ /* @{ */ @@ -59,7 +70,11 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); /* @} */ -/** @name 2. Automatic parsing +/** @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]
* * 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 @@ -148,7 +163,11 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); gras_datadesc_type_t gras_datadesc_parse(const char *name, const char *C_statement); -/** @name 3. Simple manual definitions +/** @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. @@ -277,7 +296,11 @@ int gras_datadesc_get_id(gras_datadesc_type_t ddt); /* @} */ -/** @name 4. Callback Persistant State: Simple push/pop mechanism +/** @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. @@ -342,7 +365,11 @@ void gras_datadesc_cb_push_ulint_mult(gras_datadesc_type_t typedesc, gras_cbps_t /* @} */ -/** @name 5. Callback Persistant State: Full featured mechanism +/** @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. diff --git a/include/gras/emul.h b/include/gras/emul.h index a1835095ed..addace82c4 100644 --- a/include/gras/emul.h +++ b/include/gras/emul.h @@ -18,6 +18,10 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_emul * @brief Code execution "emulation" and "virtualization". * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_globals] + *
Next [\ref GRAS_main_generation]
+ * * Emulation and virtualization words have a lot of different meanings in * computer science. Here is what we mean, and what this module allows you * to do (if it does not match your personal belives, I'm sorry): diff --git a/include/gras/messages.h b/include/gras/messages.h index d704834354..dee7f8b16c 100644 --- a/include/gras/messages.h +++ b/include/gras/messages.h @@ -20,6 +20,11 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_msg * @brief Defining messages and callbacks, and exchanging messages (Communication facility) * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_sock] + *
Next [\ref GRAS_timer] + *
Down [\ref GRAS_msg_decl]
+ * * There is two way to receive messages in GRAS. The first one is to * register a given function as callback to a given type of messages (see * \ref gras_cb_register and associated section). But you can also @@ -37,8 +42,12 @@ SG_BEGIN_DECL() * @{ */ -/** @name 1. Message declaration and retrival +/** @defgroup GRAS_msg_decl Message declaration and retrival * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg] + *
Prev + *
Next [\ref GRAS_msg_cb]
+ * * GRAS messages can only accept one type of payload. If you absolutely want to declare a message * able to convey several datatypes, you can always say that it conveys a generic reference (see * \ref gras_datadesc_ref_generic). @@ -65,8 +74,12 @@ typedef struct s_gras_msgtype *gras_msgtype_t; gras_msgtype_t gras_msgtype_by_id(int id); /** @} */ -/** @name 2. Callback declaration and use +/** @defgroup GRAS_msg_cb Callback declaration and use * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg] + *
Prev [\ref GRAS_msg_decl] + *
Next [\ref GRAS_msg_exchange]
+ * * This is how to register a given function so that it gets called when a * given type of message arrives. * @@ -101,7 +114,12 @@ typedef struct s_gras_msgtype *gras_msgtype_t; void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb); /** @} */ -/** @name 3. Message exchange */ +/** @defgroup GRAS_msg_exchange Message exchange + * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg] + *
Prev [\ref GRAS_msg_cb] + *
Next
+ */ /** @{ */ void gras_msg_send(gras_socket_t sock, @@ -114,6 +132,7 @@ typedef struct s_gras_msgtype *gras_msgtype_t; void gras_msg_handle(double timeOut); /* @} */ +/* @} */ SG_END_DECL() diff --git a/include/gras/process.h b/include/gras/process.h index 15dd07fa15..57f8b4c728 100644 --- a/include/gras/process.h +++ b/include/gras/process.h @@ -38,6 +38,10 @@ void gras_process_exit(void); /** \addtogroup GRAS_globals * \brief Handling global variables so that it works on simulator (Virtualization). * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_virtu] + *
Next [\ref GRAS_emul]
+ * * In GRAS, using globals is forbidden since the "processes" will * sometimes run as a thread inside the same process (namely, in * simulation mode). So, you have to put all globals in a structure, and diff --git a/include/gras/timer.h b/include/gras/timer.h index f12c599233..00afd4d51f 100644 --- a/include/gras/timer.h +++ b/include/gras/timer.h @@ -18,6 +18,10 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_timer * @brief Delayed and repetitive tasks (Communication facility) * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_msg] + *
Next [\ref GRAS_virtu]
+ * * This is how to have a specific function called only once after the * specified amount of time or a function executed every 5 mn until it gets * removed. In the UNIX world, this is comparable to at and diff --git a/include/gras/transport.h b/include/gras/transport.h index 1e7ceac73e..2d8961ebf7 100644 --- a/include/gras/transport.h +++ b/include/gras/transport.h @@ -13,10 +13,26 @@ /** \addtogroup GRAS_sock * \brief Socket handling (Communication facility). + * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_dd] + *
Next [\ref GRAS_msg] + *
Down [\ref GRAS_sock_create]
+ * + * The model of communications in GRAS is very close to the BSD socket one. To get two hosts + * exchanging data, one of them need to open a server socket on which it can listen for incoming messages + * and the other one must connect a client socket onto the server one. + * + * If you need an example of this, check \ref GRAS_ex_ping. + * */ - -/** \name Socket creation functions + +/** \defgroup GRAS_sock_create Socket creation functions * \ingroup GRAS_sock + * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock] + *
Prev + *
Next [\ref GRAS_sock_info]
*/ /* @{*/ /** \brief Opaque type describing a socket */ @@ -39,9 +55,13 @@ gras_socket_t gras_socket_server_ext(unsigned short port, unsigned long int bufSize, int measurement); /* @}*/ -/** \name Retrieving data about sockets and peers +/** \defgroup GRAS_sock_info Retrieving data about sockets and peers * \ingroup GRAS_sock * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock] + *
Prev [\ref GRAS_sock_create] + *
Next [\ref GRAS_sock_meas]
+ * * Who are you talking to? */ /* @{*/ @@ -54,9 +74,13 @@ int gras_socket_peer_port(gras_socket_t sock); char *gras_socket_peer_name(gras_socket_t sock); /* @}*/ -/** \name Using measurement sockets +/** \defgroup GRAS_sock_meas Using measurement sockets * \ingroup GRAS_sock * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock] + *
Prev [\ref GRAS_sock_info] + *
Next [\ref GRAS_sock_file]
+ * * You may want to use sockets not to exchange valuable data (in messages), * but to conduct some bandwidth measurements and related experiments. If so, try those measurement sockets. * @@ -80,9 +104,13 @@ gras_socket_t gras_socket_meas_accept(gras_socket_t peer); /* @}*/ -/** \name Using files as sockets +/** \defgroup GRAS_sock_file Using files as sockets * \ingroup GRAS_sock * + *
Top [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock] + *
Prev [\ref GRAS_sock_meas] + *
Next
+ * * For debugging purpose, it is possible to deal with files as if they were sockets. * It can even be useful to store stuff in a portable manner, but writing messages to a file * may be strange... diff --git a/include/gras/virtu.h b/include/gras/virtu.h index 2eb87e561c..13141489c8 100644 --- a/include/gras/virtu.h +++ b/include/gras/virtu.h @@ -16,6 +16,11 @@ SG_BEGIN_DECL() /** @addtogroup GRAS_virtu * @brief System call abstraction layer (Virtualization). + * + *
Top [\ref index]::[\ref GRAS_API] + *
Prev [\ref GRAS_timer] + *
Next [\ref GRAS_globals]
+ * * @{ */ -- 2.20.1