X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/b4deae1e2746f0e13eb74a5c9e5cb0ba71885fc0..ec63b14f8fcd0a88515e4260e00c41b77c0274cc:/doc/module-msg.doc

diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index 202c830109..cdad6beaf3 100644
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -1,27 +1,3 @@
-/** \defgroup MSG_JAVA      jMSG
-    \ingroup MSG_API
-    \brief Java bindings to MSG (\ref MSG_API)
-
-    \htmlonly <!-- 
-      DOXYGEN_NAVBAR_LABEL="JAVA bindings" 
-      DOXYGEN_NAVBAR_CHILD "Simulation functions"=classsimgrid_1_1msg_1_1Msg.html
-      DOXYGEN_NAVBAR_CHILD "Host"=classsimgrid_1_1msg_1_1Host.html
-      DOXYGEN_NAVBAR_CHILD "Process"=classsimgrid_1_1msg_1_1Process.html
-      DOXYGEN_NAVBAR_CHILD "Task"=classsimgrid_1_1msg_1_1Task.html      
-      DOXYGEN_NAVBAR_CHILD "MsgException"=classsimgrid_1_1msg_1_1MsgException.html
-    --> \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.
-*/
 
 /** \defgroup MSG_C      MSG native
     \ingroup MSG_API
@@ -38,8 +14,8 @@
       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.
+      section. To use the Java or Ruby programming interfaces, please refer to
+      the documentation provided in the relevant packages.
 */
 
 
@@ -81,14 +57,16 @@
   \section MSG_examples Examples of MSG
  
    - \ref MSG_ex_master_slave
+   - \ref MSG_ex_asynchronous_communications
+   - \ref MSG_ex_master_slave_scrip_lua
 */
 
 /** @addtogroup MSG_LUA
 
   \section MSG_Lua_funct  Lua offered functionnalities in MSG
-   - \ref host_management
-   - \ref tasks_management
-   - \ref environment_management
+   - \ref lua_host_management
+   - \ref lua_tasks_management
+   - \ref lua_environment_management
   \section Lua_examples Examples of lua MSG
  
    - \ref MSG_ex_master_slave_lua
@@ -117,6 +95,196 @@
 /**     \addtogroup msg_simulation
         \ingroup MSG_C  */
 
+
+/** \page MSG_ex_asynchronous_communications Asynchronous communication applications
+
+    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
+
+    <hr> 
+    
+    \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:
+	- <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
+	- <i>application_file</i>: 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
+
+*/
+
+/** \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
+
+<hr> 
+    
+    \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:
+	- <i>platform_script_file</i>: 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
     
     Simulation of a master-slave application using a realistic platform and
@@ -233,7 +401,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 +454,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