From: mquinson Date: Mon, 7 Feb 2005 22:40:20 +0000 (+0000) Subject: doxygenification X-Git-Tag: v3.3~4449 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/2fad952ef4a63aedf6c8b2dc4e371de849f1e163 doxygenification git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@902 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/include/gras/cond.h b/include/gras/cond.h index 2aa07db621..99ac27773b 100644 --- a/include/gras/cond.h +++ b/include/gras/cond.h @@ -15,20 +15,23 @@ BEGIN_DECL() -/** - * gras_if_RL: +/** @addtogroup GRAS_cond + * @brief Handling code specific to the simulation or to the reality (Virtualization). * - * Returns true only if the program runs on real life + * Please note that those are real functions and not pre-processor defines. This is to ensure + * that the same object code can be linked against the SG library or the RL one without recompilation. + * + * @{ */ + +/** \brief Returns true only if the program runs on real life */ int gras_if_RL(void); -/** - * gras_if_SG: - * - * Returns true only if the program runs within the simulator - */ +/** \brief Returns true only if the program runs within the simulator */ int gras_if_SG(void); +/** @} */ + END_DECL() #endif /* GRAS_COND_H */ diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index 23dfa4cea7..532dfdd43b 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -14,7 +14,7 @@ BEGIN_DECL() -/** @defgroup GRAS_dd Data description +/** @addtogroup GRAS_dd Data description * @brief Describing data to be exchanged (Communication facility) * * @section Overview @@ -33,9 +33,9 @@ BEGIN_DECL() * - d) Callback Persistant State: Simple push/pop mecanism * - e) Callback Persistant State: Full featured mecanism */ - +/*@{*/ + /** @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: @@ -59,7 +59,6 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); /* @} */ /** @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 @@ -132,7 +131,6 @@ 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. @@ -273,7 +271,6 @@ int gras_datadesc_get_id(gras_datadesc_type_t ddt); /*@}*/ /** @name d) 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. @@ -311,7 +308,6 @@ void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data); /*@}*/ /** @name e) 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. @@ -346,6 +342,7 @@ void gras_cbps_block_end(gras_cbps_t ps); /* @} */ +/*@}*/ /******************************* diff --git a/include/gras/messages.h b/include/gras/messages.h index 9a17eae998..bd56c82bd4 100644 --- a/include/gras/messages.h +++ b/include/gras/messages.h @@ -17,46 +17,85 @@ BEGIN_DECL() -/* msgtype declaration and retrival */ +/** @addtogroup GRAS_msg + * @brief Defining messages and callbacks, and exchanging messages (Communication facility) + * @{ + */ + +/** @name Message declaration and retrival + * + * 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). + * + * In order to ease the upgrade of GRAS applications, it is possible to \e version the messages, ie + * to add a version number to the message (by default, the version is set to 0). Any messages of the + * wrong version will be ignored by the applications not providing any specific callback for them. + * + * This mecanism (stolen from the dynamic loader one) should ensure you to change the semantic of a given + * message while still understanding the old one. + */ +/** @{ */ +/** \brief Opaque type */ typedef struct s_gras_msgtype *gras_msgtype_t; +/** \brief declare a new message type of the given name. It only accepts the given datadesc as payload */ void gras_msgtype_declare (const char *name, gras_datadesc_type_t payload); +/** \brief declare a new versionned message type of the given name and payload. */ void gras_msgtype_declare_v(const char *name, short int version, gras_datadesc_type_t payload); +/** \brief retrive an existing message type from its name. */ gras_msgtype_t gras_msgtype_by_name (const char *name); +/** \brief retrive an existing message type from its name and version number. */ gras_msgtype_t gras_msgtype_by_namev(const char *name, short int version); +/** @} */ -/** - * gras_cb_t: - * @msg: The message itself - * @Returns: true if the message was consumed by the callback. +/** @name Callback declaration and use */ +/** @{ */ +/** \brief Type of message callback functions. + * \param msg: The message itself + * \return true if the message was consumed by the callback, false if the message was + * refused by the callback (and should be passed to the next callback of the stack for + * this message) * - * Type of message callback functions. Once a such a function is registered to - * handle messages of a given type with RegisterCallback(), it will be called - * each time such a message incomes. + * Once a such a function is registered to handle messages of a given type with + * \ref gras_cb_register(), it will be called each time such a message arrives. * * If the callback accepts the message, it should free it after use. */ typedef int (*gras_cb_t)(gras_socket_t expeditor, void *payload); +/** \brief Bind the given callback to the given message type + * + * Several callbacks can be attached to a given message type. The lastly added one will get the message first, and + * if it returns false, the message will be passed to the second one. + * And so on until one of the callbacks accepts the message. + */ void gras_cb_register (gras_msgtype_t msgtype, gras_cb_t cb); +/** \brief Unbind the given callback from the given message type */ void gras_cb_unregister(gras_msgtype_t msgtype, gras_cb_t cb); +/** @} */ +/** @name Message exchange */ +/** @{ */ +/** \brief Send the data pointed by \a payload as a message of type \a msgtype to the peer \a sock */ xbt_error_t gras_msg_send(gras_socket_t sock, gras_msgtype_t msgtype, void *payload); +/** \brief Waits for a message to come in over a given socket. */ xbt_error_t gras_msg_wait(double timeout, gras_msgtype_t msgt_want, gras_socket_t *expeditor, void *payload); xbt_error_t gras_msg_handle(double timeOut); +/*@}*/ END_DECL() diff --git a/include/gras/process.h b/include/gras/process.h index 5a6d6b38d3..5ffcad6fc6 100644 --- a/include/gras/process.h +++ b/include/gras/process.h @@ -34,6 +34,21 @@ xbt_error_t gras_process_exit(void); /****************************************************************************/ /* Manipulating User Data */ /****************************************************************************/ + +/** \addtogroup GRAS_globals + * \brief Handling global variables so that it works on simulator (Virtualization). + * + * 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 + * let GRAS handle it. + * + * Use the \ref gras_userdata_new macro to create a new user data (or malloc it + * and use \ref gras_userdata_set yourself), and \ref gras_userdata_get to + * retrive a reference to it. + */ +/*@{*/ + /** * \brief Get the data associated with the current process. * \ingroup GRAS_globals @@ -46,12 +61,9 @@ void *gras_userdata_get(void); */ void gras_userdata_set(void *ud); -/** - * \brief Malloc and set the data associated with the current process. - * \ingroup GRAS_globals - */ - +/** \brief Malloc and set the data associated with the current process. */ #define gras_userdata_new(type) (gras_userdata_set(xbt_new0(type,1)),gras_userdata_get()) +/*@}*/ END_DECL() diff --git a/include/gras/transport.h b/include/gras/transport.h index db4df12aa7..84c711336a 100644 --- a/include/gras/transport.h +++ b/include/gras/transport.h @@ -13,32 +13,66 @@ #include "xbt/error.h" +/** \addtogroup GRAS_sock + * \brief Socket handling (Communication facility). + */ + +/** \name Socket creation functions + * \ingroup GRAS_sock + */ +/*@{*/ +/** \brief Opaque type describing a socket */ typedef struct s_gras_socket *gras_socket_t; +/** \brief Simply create a client socket (to speak to a remote host) */ xbt_error_t gras_socket_client(const char *host, unsigned short port, /* OUT */ gras_socket_t *dst); +/** \brief Simply create a server socket (to ear from remote hosts speaking to you) */ xbt_error_t gras_socket_server(unsigned short port, /* OUT */ gras_socket_t *dst); +/** \brief Close socket */ void gras_socket_close(gras_socket_t sd); -/* get information about socket */ -int gras_socket_my_port (gras_socket_t sock); -int gras_socket_peer_port(gras_socket_t sock); -char *gras_socket_peer_name(gras_socket_t sock); - -/* extended interface to get all details */ +/** \brief Create a client socket, full interface to all relevant settings */ xbt_error_t gras_socket_client_ext(const char *host, unsigned short port, unsigned long int bufSize, int raw, /* OUT */ gras_socket_t *dst); +/** \brief Create a server socket, full interface to all relevant settings */ xbt_error_t gras_socket_server_ext(unsigned short port, unsigned long int bufSize, int raw, /* OUT */ gras_socket_t *dst); +/*@}*/ +/** \name Retrieving data about sockets and peers + * \ingroup GRAS_sock + * + * Who are you talking to? + */ +/*@{*/ + +/** Get the port number on which this socket is connected on my side */ +int gras_socket_my_port (gras_socket_t sock); +/** Get the port number on which this socket is connected on remote side */ +int gras_socket_peer_port(gras_socket_t sock); +/** Get the host name of the remote side */ +char *gras_socket_peer_name(gras_socket_t sock); +/*@}*/ + +/** \name Using raw sockets + * \ingroup GRAS_sock + * + * You may want to use sockets not to exchange valuable data (in messages), + * but to conduct some experiments such as bandwidth measurement. If so, try those raw sockets. + * + * You can only use those functions on sockets openned with the "raw" boolean set to true. + * + * \bug Raw sockets are not fully functionnal yet. + */ +/*@{*/ -/* using raw sockets */ xbt_error_t gras_socket_raw_send(gras_socket_t peer, unsigned int timeout, unsigned long int expSize, @@ -48,11 +82,24 @@ xbt_error_t gras_socket_raw_recv(gras_socket_t peer, unsigned long int expSize, unsigned long int msgSize); +/*@}*/ + +/** \name Using files as sockets + * \ingroup GRAS_sock + * + * 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... + * + * \bug Don't use '-' on windows. this file represents stdin or stdout, but I failed to deal with it on windows. + */ +/*@{*/ /* debuging functions */ xbt_error_t gras_socket_client_from_file(const char*path, /* OUT */ gras_socket_t *dst); xbt_error_t gras_socket_server_from_file(const char*path, /* OUT */ gras_socket_t *dst); +/*@}*/ #endif /* GRAS_TRANSPORT_H */ diff --git a/include/gras/virtu.h b/include/gras/virtu.h index 3ec1ab9324..51939be681 100644 --- a/include/gras/virtu.h +++ b/include/gras/virtu.h @@ -14,26 +14,24 @@ BEGIN_DECL() -/** - * gras_os_time: - * @Returns: number of second since the Epoch. - * (00:00:00 UTC, January 1, 1970 in Real Life, and begining of simulation in SG) - * - * Get the current time. +/** @addtogroup GRAS_virtu + * @brief System call abstraction layer (Virtualization). + * @{ + */ + +/** @brief Get the current time + * @return number of second since the Epoch. + * (00:00:00 UTC, January 1, 1970 in Real Life, and begining of simulation in SG) */ double gras_os_time(void); -/** - * gras_os_sleep: - * @Param1: number of seconds to sleep - * @Param2: number of microseconds to sleep - * - * sleeps for the given amount of time. +/** @brief sleeps for the given amount of time. + * @param sec: number of seconds to sleep + * @param usec: number of microseconds to sleep */ void gras_os_sleep(unsigned long sec, unsigned long usec); -/** - * gras_get_my_fqdn: +/** @brief get the fully-qualified name of the current host * * Returns the fully-qualified name of the host machine, or NULL if the name * cannot be determined. Always returns the same value, so multiple calls @@ -42,6 +40,7 @@ void gras_os_sleep(unsigned long sec, unsigned long usec); const char * gras_get_my_fqdn(void); +/** @} */ END_DECL() #endif /* GRAS_VIRTU_H */ diff --git a/src/gras/Msg/msg.c b/src/gras/Msg/msg.c index a8eb12e17a..72dfef3b9d 100644 --- a/src/gras/Msg/msg.c +++ b/src/gras/Msg/msg.c @@ -19,9 +19,7 @@ xbt_set_t _gras_msgtype_set = NULL; static char GRAS_header[6]; static char *make_namev(const char *name, short int ver); -/** - * gras_msg_init: - * +/* * Initialize this submodule. */ void gras_msg_init(void) { @@ -38,20 +36,16 @@ void gras_msg_init(void) { GRAS_header[5]=(char)GRAS_THISARCH; } -/** - * gras_msg_exit: - * +/* * Finalize the msg module - **/ + */ void gras_msg_exit(void) { VERB0("Exiting Msg"); xbt_set_free(&_gras_msgtype_set); } -/** - * gras_msgtype_free: - * +/* * Reclamed memory */ void gras_msgtype_free(void *t) { @@ -83,11 +77,8 @@ static char *make_namev(const char *name, short int ver) { } /** - * gras_msgtype_declare: - * @name: name as it should be used for logging messages (must be uniq) - * @payload: datadescription of the payload - * - * Registers a message to the GRAS mecanism. + * @param name: name as it should be used for logging messages (must be uniq) + * @param payload: datadescription of the payload */ void gras_msgtype_declare(const char *name, gras_datadesc_type_t payload) { @@ -95,10 +86,9 @@ void gras_msgtype_declare(const char *name, } /** - * gras_msgtype_declare_v: - * @name: name as it should be used for logging messages (must be uniq) - * @version: something like versionning symbol - * @payload: datadescription of the payload + * @param name: name as it should be used for logging messages (must be uniq) + * @param version: something like versionning symbol + * @param payload: datadescription of the payload * * Registers a message to the GRAS mecanism. Use this version instead of * gras_msgtype_declare when you change the semantic or syntax of a message and @@ -143,18 +133,14 @@ gras_msgtype_declare_v(const char *name, &gras_msgtype_free); } -/** - * gras_msgtype_by_name: - * - * Retrieve a datatype description from its name +/* + * Retrieve a msgtype description from its name */ gras_msgtype_t gras_msgtype_by_name (const char *name) { return gras_msgtype_by_namev(name,0); } -/** - * gras_msgtype_by_namev: - * - * Retrieve a datatype description from its name and version +/* + * Retrieve a msgtype description from its name and version */ gras_msgtype_t gras_msgtype_by_namev(const char *name, short int version) { @@ -175,9 +161,7 @@ gras_msgtype_t gras_msgtype_by_namev(const char *name, return res; } -/** - * gras_msg_send: - * +/* * Send the given message on the given socket */ xbt_error_t @@ -207,9 +191,7 @@ gras_msg_send(gras_socket_t sock, return no_error; } -/** - * gras_msg_recv: - * +/* * receive the next message on the given socket. */ xbt_error_t @@ -263,12 +245,11 @@ gras_msg_recv(gras_socket_t sock, } /** - * gras_msg_wait: - * @timeout: How long should we wait for this message. - * @id: id of awaited msg - * @Returns: the error code (or no_error). - * - * Waits for a message to come in over a given socket. + * @param timeout: How long should we wait for this message. + * @param msgt_want: type of awaited msg + * @param[out] expeditor: where to create a socket to answer the incomming message + * @param[out] payload: where to write the payload of the incomming message + * @return the error code (or no_error). * * Every message of another type received before the one waited will be queued * and used by subsequent call to this function or MsgHandle(). @@ -337,12 +318,11 @@ gras_msg_wait(double timeout, } /** - * gras_msg_handle: - * @timeOut: How long to wait for incoming messages - * @Returns: the error code (or no_error). + * @param timeOut: How long to wait for incoming messages + * @return the error code (or no_error). * - * Waits up to #timeOut# seconds to see if a message comes in; if so, calls the - * registered listener for that message (see RegisterCallback()). + * Waits up to \a timeOut seconds to see if a message comes in; if so, calls the + * registered listener for that message (see \ref gras_cb_register()). */ xbt_error_t gras_msg_handle(double timeOut) { diff --git a/src/gras/Virtu/sg_time.c b/src/gras/Virtu/sg_time.c index 85b014c70f..d83b25780e 100644 --- a/src/gras/Virtu/sg_time.c +++ b/src/gras/Virtu/sg_time.c @@ -9,21 +9,14 @@ #include "gras/Virtu/virtu_sg.h" -/** - * gras_time: - * @Returns: The current time - * - * The epoch since when the time is given is not specified. It is thus only usefull to compute intervals +/* + * Time elapsed since the begining of the simulation. */ double gras_os_time() { return MSG_getClock(); } -/** - * gras_sleep: - * @sec: amount of sec to sleep - * @usec: amount of micro second to sleep - * +/* * Freeze the process for the specified amount of time */ void gras_os_sleep(unsigned long sec,unsigned long usec) { diff --git a/src/modules.doc b/src/modules.doc index 69678ba6ac..cc1c756473 100644 --- a/src/modules.doc +++ b/src/modules.doc @@ -62,6 +62,8 @@ MSG was the first distributed programming environment provided within SimGrid. While almost realistic, it remains quite simple (simplistic?). + \section MSG_who Who should use this (and who shouldn't) + You should use this model if you want to study some heuristics for a given problem you don't really want to implement. If you want to get a real implementation of your solution, have a look at the \ref GRAS_API @@ -104,6 +106,8 @@ encompassing both developer helping tools (the simulator and associated tools) and an efficient while portable execution runtime. + \section GRAS_who Who should use this (and who shouldn't) + You should use this programming environment if you want to develop real applications, ie if the final result of your work is a program which may eventually be distributed. @@ -116,42 +120,42 @@ consider implementing your own directly on top of \ref SURF_API (but you probably want to contact us before). - The user visibile features tend to offer several kind of functionnalities: + \section GRAS_funct Offered functionnalities - Communication facilities: Exchanging messages between peers + - \ref GRAS_dd: any data which may transit on the network must be + described beforehand so that GRAS can handle the platform + heterogeneity and convert them if needed. + - \ref GRAS_sock: this is how to open a communication channel to + other processes, and retrive information about them. + - \ref GRAS_msg: communications are message oriented. You have to + describe all possible messages and their payload beforehand, and + can then attach callbacks to the arrival of a given kind of message. - Virtualization: Running both on top of the simulator and on top of real platforms, and portability support. + - \ref GRAS_globals: The use of globals is forbidden since the + "processes" are threads in simulation mode. \n + This is how to let GRAS handle your globals properly. + - \ref GRAS_cond: How to declare specific code for the simulation mode + or for the real mode. + - \ref GRAS_virtu: You naturally don't want to call the + gettimeofday(2) function in simulation mode since it would give + you the time on the host running the simulation, not the time in + the simulated world (you are belonging to).\n + This a system call virtualization layer, which also acts as a + portability layer. + + @{ */ -/** \addtogroup GRAS_implem - \ingroup GRAS_API - - Internals of GRAS (forget it) */ -/** \addtogroup GRAS_dd - \ingroup GRAS_API */ -/** \addtogroup GRAS_dd_implem - \ingroup GRAS_implem */ -/** \defgroup GRAS_sock Sockets - \ingroup GRAS_API - \brief Open/close sockets, and get info on peer (Communication facility). */ -/** \defgroup GRAS_msg Messages - \ingroup GRAS_API - \brief Defining messages and callbacks, and sending/receiving messages (Communication facility). - */ -/** \defgroup GRAS_globals Globals - \ingroup GRAS_API - \brief Handling global variables so that it works on simulator (Virtualization). - - 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 - let GRAS handle it. - - Use the \ref gras_userdata_new macro to create a new user data (or malloc it - and use \ref gras_userdata_set yourself), and \ref gras_userdata_get to - retrive a reference to it. */ -/** \defgroup GRAS_virtu Syscalls - \ingroup GRAS_API - \brief System call abstraction layer (Virtualization). */ + /** \defgroup GRAS_dd Data description */ + /** \defgroup GRAS_sock Sockets */ + /** \defgroup GRAS_msg Messages */ + + /** \defgroup GRAS_globals Globals */ + /** \defgroup GRAS_cond Conditional execution */ + /** \defgroup GRAS_virtu Syscalls */ + +/** @} */ /** \defgroup SMPI_API SMPI \ingroup SimGrid_API @@ -162,6 +166,8 @@ for that. In other words, it will constitute an emulation solution for parallel codes. + \section SMPI_who Who should use this (and who shouldn't) + You should use this programming environment of the SimGrid suite if you want to study existing MPI applications. If you want to work on a distributed application, have a look at the