/** @addtogroup GRAS_dd Data description
* @brief Describing data to be exchanged (Communication facility)
*
- * @section Overview
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td>Prev <td>
+ * <tr><td><b>Next</b> <td> [\ref GRAS_sock]
+ * <tr><td><b>Down</b> <td> [\ref GRAS_dd_basic] </table></center>
*
* 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
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ * <tr><td> Prev <td>
+ * <tr><td><b>Next</b> <td> [\ref GRAS_dd_auto] </table></center>
*
* 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:
* 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
+ *
*/
/* @{ */
/* @} */
-/** @name 2. Automatic parsing
+/** @defgroup GRAS_dd_auto Automatic parsing of data descriptions
+ * @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_dd_basic]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_dd_manual] </table></center>
*
* 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
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
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_dd_auto]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_dd_cb_simple] </table></center>
*
* Here are the functions to use if you want to declare your description manually.
* The function names should be self-explanatory in most cases.
/* @} */
-/** @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
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_dd_manual]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_dd_cb_full] </table></center>
*
* 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.
/* @} */
-/** @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
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_dd_cb_simple]
+ * <tr><td>Next <td> </table></center>
*
* 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.
/** @addtogroup GRAS_emul
* @brief Code execution "emulation" and "virtualization".
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_globals]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_main_generation] </table></center>
+ *
* 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):
/** @addtogroup GRAS_msg
* @brief Defining messages and callbacks, and exchanging messages (Communication facility)
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_sock]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_timer]
+ * <tr><td><b>Down</b> <td> [\ref GRAS_msg_decl] </table></center>
+ *
* 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
* @{
*/
-/** @name 1. Message declaration and retrival
+/** @defgroup GRAS_msg_decl Message declaration and retrival
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ * <tr><td> Prev <td>
+ * <tr><td><b>Next</b> <td> [\ref GRAS_msg_cb] </table></center>
+ *
* 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).
gras_msgtype_t gras_msgtype_by_id(int id);
/** @} */
-/** @name 2. Callback declaration and use
+/** @defgroup GRAS_msg_cb Callback declaration and use
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_msg_decl]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_msg_exchange] </table></center>
+ *
* This is how to register a given function so that it gets called when a
* given type of message arrives.
*
void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb);
/** @} */
-/** @name 3. Message exchange */
+/** @defgroup GRAS_msg_exchange Message exchange
+ *
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_msg_cb]
+ * <tr><td> Next <td> </table></center>
+ */
/** @{ */
void gras_msg_send(gras_socket_t sock,
void gras_msg_handle(double timeOut);
/* @} */
+/* @} */
SG_END_DECL()
/** \addtogroup GRAS_globals
* \brief Handling global variables so that it works on simulator (Virtualization).
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_virtu]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_emul] </table></center>
+ *
* 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
/** @addtogroup GRAS_timer
* @brief Delayed and repetitive tasks (Communication facility)
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_msg]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_virtu] </table></center>
+ *
* 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 <tt>at</tt> and
/** \addtogroup GRAS_sock
* \brief Socket handling (Communication facility).
+ *
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_dd]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_msg]
+ * <tr><td><b>Down</b> <td> [\ref GRAS_sock_create] </table></center>
+ *
+ * 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 <i>server</i> socket on which it can listen for incoming messages
+ * and the other one must connect a <i>client</i> 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
+ *
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ * <tr><td>Prev <td>
+ * <tr><td><b>Next</b> <td> [\ref GRAS_sock_info] </table></center>
*/
/* @{*/
/** \brief Opaque type describing a socket */
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
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_sock_create]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_sock_meas] </table></center>
+ *
* Who are you talking to?
*/
/* @{*/
char *gras_socket_peer_name(gras_socket_t sock);
/* @}*/
-/** \name Using measurement sockets
+/** \defgroup GRAS_sock_meas Using measurement sockets
* \ingroup GRAS_sock
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_sock_info]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_sock_file] </table></center>
+ *
* 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.
*
/* @}*/
-/** \name Using files as sockets
+/** \defgroup GRAS_sock_file Using files as sockets
* \ingroup GRAS_sock
*
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_sock_meas]
+ * <tr><td>Next <td> </table></center>
+ *
* 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...
/** @addtogroup GRAS_virtu
* @brief System call abstraction layer (Virtualization).
+ *
+ * <center><table><tr><td><b>Top</b> <td> [\ref index]::[\ref GRAS_API]
+ * <tr><td><b>Prev</b> <td> [\ref GRAS_timer]
+ * <tr><td><b>Next</b> <td> [\ref GRAS_globals] </table></center>
+ *
* @{
*/