X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/b4deae1e2746f0e13eb74a5c9e5cb0ba71885fc0..05db1dcff50b437219a10237de09ec792e40a840:/doc/module-msg.doc diff --git a/doc/module-msg.doc b/doc/module-msg.doc index 202c830109..d94fd0d3ce 100644 --- a/doc/module-msg.doc +++ b/doc/module-msg.doc @@ -1,34 +1,5 @@ -/** \defgroup MSG_JAVA jMSG - \ingroup MSG_API - \brief Java bindings to MSG (\ref MSG_API) - - \htmlonly \endhtmlonly - - MSG was the first distributed programming environment provided within - SimGrid. While almost realistic, it remains quite simple (simplistic?). - This describes the Java bindings to this interface. - - \section jMSG_who Who should use this (and who shouldn't) - - You should use MSG if you want to study some heuristics for a - given problem you don't really want to implement. If you want to - use the Java programming language, your are in the right - section. To use the C interface, please refer to \ref MSG_C. -*/ +/** \addtogroup MSG_API -/** \defgroup MSG_C MSG native - \ingroup MSG_API - \brief Native interface to MSG (\ref MSG_API) - - \htmlonly \endhtmlonly - MSG was the first distributed programming environment provided within SimGrid. While almost realistic, it remains quite simple (simplistic?). This describes the native to MSG. @@ -38,86 +9,242 @@ You should use MSG if you want to study some heuristics for a given problem you don't really want to implement. If you want to use the C programming language, your are in the right - section. To use the Java programming interface, please refer to - \ref MSG_JAVA. -*/ - - -/** - -\defgroup MSG_LUA lMSG - \ingroup MSG_API - \brief Lua bindings to MSG (\ref MSG_API) - - \htmlonly \endhtmlonly - - MSG was the first distributed programming environment provided within - SimGrid. While almost realistic, it remains quite simple (simplistic?). - This describes the Lua bindings to this interface. - - \section lMSG_who Who should use this (and who shouldn't) - - You should use MSG if you want to study some heuristics for a - given problem you don't really want to implement. If you want to - use the Lua script language, your are in the right - section. To use the C interface, please refer to \ref MSG_C. - -*/ - -/** @addtogroup MSG_C + section. To use the Java or Ruby programming interfaces, please refer to + the documentation provided in the relevant packages. \section MSG_funct Offered functionnalities - \ref m_process_management - \ref m_datatypes_management - \ref m_host_management - \ref m_task_management + - \ref m_file_management + - \ref msg_actions_functions - \ref msg_gos_functions - - \ref m_channel_management - \ref msg_easier_life - \ref msg_simulation - \section MSG_examples Examples of MSG + Also make sure to visit the page @ref MSG_examples. +*/ + + +/** @defgroup m_datatypes_management MSG Data Types + @ingroup MSG_API + @brief This section describes the different datatypes provided by MSG. + + \htmlonly \endhtmlonly +*/ + +/** @defgroup m_process_management Management Functions of Agents + * @ingroup MSG_API + * @brief This section describes the agent structure of MSG + * (#m_process_t) and the functions for managing it. + */ + +/** @defgroup m_host_management Management functions of Hosts + * @ingroup MSG_API + * @brief This section describes the host structure of MSG + */ + +/** @defgroup m_task_management Managing functions of Tasks + * @ingroup MSG_API + * @brief This section describes the task structure of MSG + * (#m_task_t) and the functions for managing it. + */ + + /** @defgroup m_file_management Managing functions of Files + * @ingroup MSG_API + * @brief This section describes the file structure of MSG + * (#m_file_t) and the functions for managing it. It + * is based on POSIX functions. + */ + +/** @defgroup msg_actions_functions Managing actions + * @ingroup MSG_API + * @brief This section describes functions for managing actions. + */ + +/** @defgroup msg_gos_functions MSG Operating System Functions + * @ingroup MSG_API + * @brief This section describes the functions that can be used + * by an agent for handling some task. + */ + +/** @defgroup msg_easier_life Platform and Application management + * @ingroup MSG_API + * @brief This section describes functions to manage the platform creation + * and the application deployment. Please check @ref + * MSG_examples for an overview of their usage. + */ - - \ref MSG_ex_master_slave +/** @defgroup msg_simulation MSG simulation Functions +* @ingroup MSG_API +* @brief This section describes the functions you need to know to +* set up a simulation. You should have a look at \ref MSG_examples +* to have an overview of their usage. +* +* @htmlonly @endhtmlonly */ -/** @addtogroup MSG_LUA +/** +@defgroup MSG_examples MSG Examples +@ingroup MSG_API + +MSG comes with an extensive set of examples. It is sometimes difficult +to find the one you need. This list aims at helping you finding the +example from which you can learn what you want to. + +@section MSG_ex_basics Basic examples and features + +*/ + +/** +@defgroup MSG_LUA Lua bindings +@ingroup MSG_API +@brief Lua bindings to MSG (\ref MSG_API) + +@htmlonly @endhtmlonly + + This is the lua bindings of the \ref MSG_API interface. + + \section lMSG_who Who should use this (and who shouldn't) + + If you want to use MSG to study your algorithm, but you don't + want to use the C language (using \ref MSG_API), then you should + use some bindings such as this one. The advantage of the lua + bindings is that they are distributed directly with the main + archive (in contrary to Java and Ruby bindings, for example, + that are distributed separately). Another advantage of lua is + that there is almost no performance loss with regard to the C + version (at least there shouln't be any -- it is still to be + precisely assessed). \section MSG_Lua_funct Lua offered functionnalities in MSG - - \ref host_management - - \ref tasks_management - - \ref environment_management + Almost all important features of the MSG interface are available + from the lua bindings. Unfortunately, since doxygen does not support + the lua modules implemented directly in C as we are using, there is + no ready to use reference documentation for this module. Even more + than for the other modules, you will have to dig into the source + code of the examples to learn how to use it. + \section Lua_examples Examples of lua MSG - \ref MSG_ex_master_slave_lua - \ref MSG_ex_master_slave_lua_bypass + - Also, the lua version of the Chord example (in the source tree) + is a working non-trivial example of use of the lua bindings */ -/** @defgroup m_datatypes_management MSG Data Types - @ingroup MSG_C - @brief This section describes the different datatypes provided by MSG. +/** \defgroup MSG_ex_asynchronous_communications Asynchronous communications + \ingroup MSG_examples + + Simulation of asynchronous communications between a sender and a receiver using a realistic platform and + an external description of the deployment. + + \section MSG_ex_ms_TOC Table of contents: + - \ref MSG_ext_icomms_code + - \ref MSG_ext_icomms_preliminary + - \ref MSG_ext_icomms_Sender + - \ref MSG_ext_icomms_Receiver + - \ref MSG_ext_icomms_core + - \ref MSG_ext_icomms_Main + - \ref MSG_ext_icomms_fct_Waitall + - \ref MSG_ext_icomms_fct_Waitany + +
- \htmlonly \endhtmlonly + \dontinclude msg/icomms/peer.c + + \section MSG_ext_icomms_code Code of the application + + \subsection MSG_ext_icomms_preliminary Preliminary declarations + \skip include + \until Sender function + + \subsection MSG_ext_icomms_Sender Sender function + + The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking + we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()". + It also available to "make MSG_comm_wait()" which make both of them. + + C style arguments (argc/argv) are interpreted as: + - the number of tasks to distribute + - the computation size of each task + - the size of the files associated to each task + - a list of host that will accept those tasks. + - the time to sleep at the beginning of the function + - This time defined the process sleep time + if time = 0 use of MSG_comm_wait() + if time > 0 use of MSG_comm_test() + + + \until Receiver function + + \subsection MSG_ext_icomms_Receiver Receiver function + + This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know + if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()". + + C style arguments (argc/argv) are interpreted as: + - the id to use for received the communication. + - the time to sleep at the beginning of the function + - This time defined the process sleep time + if time = 0 use of MSG_comm_wait() + if time > 0 use of MSG_comm_test() + + \until Test function + + \subsection MSG_ext_icomms_core Simulation core + + This function is the core of the simulation and is divided only into 3 parts + thanks to MSG_create_environment() and MSG_launch_application(). + -# Simulation settings : MSG_create_environment() creates a realistic + environment + -# Application deployment : create the agents on the right locations with + MSG_launch_application() + -# The simulation is run with #MSG_main() + + Its arguments are: + - platform_file: the name of a file containing an valid surfxml platform description. + - application_file: the name of a file containing a valid surfxml application description + + \until Main function + + \subsection MSG_ext_icomms_Main Main function + + This initializes MSG, runs a simulation, and free all data-structures created by MSG. + + \until end_of_main + + \dontinclude msg/icomms/peer2.c + + \section MSG_ext_icomms_fct_Waitall Waitall function for sender + + The use of this function permit to send all messages and wait for the completion of all in one time. + + \skipline Sender function + \until end_of_sender + + \section MSG_ext_icomms_fct_Waitany Waitany function + + The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table. + + \subsection MSG_ext_icomms_fct_Waitany_sender From a sender + We can use this function to wait all sended messages. + \dontinclude msg/icomms/peer3.c + \skipline Sender function + \until end_of_sender + + \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver + We can also wait for the receiving of all messages. + \dontinclude msg/icomms/peer3.c + \skipline Receiver function + \until end_of_receiver + */ -/** \addtogroup m_process_management - \ingroup MSG_C */ -/** \addtogroup m_host_management - \ingroup MSG_C */ -/** \addtogroup m_task_management - \ingroup MSG_C */ -/** \addtogroup msg_gos_functions - \ingroup MSG_C */ -/** \addtogroup m_channel_management - \ingroup MSG_C */ -/** \addtogroup msg_easier_life - \ingroup MSG_C */ -/** \addtogroup msg_simulation - \ingroup MSG_C */ - -/** \page MSG_ex_master_slave Master/slave application + +/** @defgroup MSG_ex_master_slave Basic Master/Slaves + @ingroup MSG_examples Simulation of a master-slave application using a realistic platform and an external description of the deployment. @@ -233,7 +360,7 @@ - \ref MSG_ext_ms_platform - \dontinclude lua/master_slave.lua + \dontinclude lua/masterslave/master_slave.lua \section MSG_ext_ms_code_lua Code of the application @@ -286,7 +413,7 @@ - \ref MSG_ext_ms_core_lua - \dontinclude lua/master_slave_bypass.lua + \dontinclude lua/console/master_slave_bypass.lua \section MSG_ext_ms_code_lua Code of the application @@ -328,3 +455,4 @@ \until simgrid.clean() */ +