X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d7de2f8eb00821d8def1edf69bd77a4a54256fa8..63a42d009b40cf8bc11338a13b396efb76ab38cb:/doc/module-msg.doc
diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index cdad6beaf3..698d3f3e49 100644
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -1,10 +1,5 @@
+/** \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.
@@ -16,87 +11,139 @@
use the C programming language, your are in the right
section. To use the Java or Ruby programming interfaces, please refer to
the documentation provided in the relevant packages.
-*/
-
-
-/**
-
-\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 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_deprecated_functions
- \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_deprecated_functions MSG Deprecated
+ * @ingroup MSG_API
+ * @brief This section describes the deprecated functions and. They
+ * should be remove on next release.
+ */
- - \ref MSG_ex_master_slave
- - \ref MSG_ex_asynchronous_communications
- - \ref MSG_ex_master_slave_scrip_lua
+/** @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.
+ */
+
+/** @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 lua_host_management
- - \ref lua_tasks_management
- - \ref lua_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.
-
- \htmlonly \endhtmlonly
-*/
-/** \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_asynchronous_communications Asynchronous communication applications
+/** \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.
@@ -203,89 +250,8 @@
*/
-/** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
-
- Simulation of a master-slave application using a realistic platform and
- an external description of the deployment via a lua script.
-
- \section MSG_ex_msl_TOC Table of contents:
-
- - \ref MSG_ext_msl_code
- - \ref MSG_ext_msl_preliminary
- - \ref MSG_ext_msl_master
- - \ref MSG_ext_msl_slave
- - \ref MSG_ext_msl_core
- - \ref MSG_ext_msl_main
- - \ref MSG_ext_msl_helping
- - \ref MSG_ext_msl_platform
-
-
-
- \dontinclude msg/masterslave/masterslave_console.c
-
- \section MSG_ext_msl_code Code of the application
-
- \subsection MSG_ext_msl_preliminary Preliminary declarations
-
- \skip include
- \until } channel_t;
-
- \subsection MSG_ext_msl_master Master code
-
- This function has to be assigned to a m_process_t that will behave as the master.
- It should not be called directly but either given as a parameter to
- #MSG_process_create() or registered as a public function through
- #MSG_function_register() and then automatically assigned to a process through
- #MSG_load_platform_script().
-
- 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
- - number of hosts that will accept those tasks.
-
- Tasks are dumbly sent in a round-robin style.
-
- \until end_of_master
-\subsection MSG_ext_msl_slave Slave code
-
- This function has to be assigned to a #m_process_t that has to behave as a slave.
- Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
-
- This function keeps waiting for tasks and executes them as it receives them.
-
- \until end_of_slave
-
-\subsection MSG_ext_msl_core Simulation core
-
- This function is the core of the simulation and is divided now only into 2 parts
- thanks to MSG_load_platform_script().
- -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic
- environment and the agents on the right locations, described in the lua script file (see example below).
- Note that the use of this function require a lua installation on your machine.
- -# The simulation is run with #MSG_main().
-
- Its arguments are:
- - platform_script_file: the name of the script file containing a valid platform and application description, using bound lua methods to bypass the surfxml parser.
-
- \until end_of_test_all
-
-\subsection MSG_ext_msl_main Main() function
-
- This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-
- \until end_of_main
-
- \section MSG_ext_msl_helping Helping files
-
- \subsection MSG_ext_msl_platform Example of platform script file
-
- \include msg/masterslave/platform_script.lua
-
-
-*/
-
-/** \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.
@@ -496,3 +462,4 @@
\until simgrid.clean()
*/
+