X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/92bb2be06658bec5abe69a30642ed469e47708fd..e04390ba0f56cd9e99253f4756c65739ca0a303e:/examples/msg/msg_test.c

diff --git a/examples/msg/msg_test.c b/examples/msg/msg_test.c
index 06adbb9ecf..cf6136e84f 100644
--- a/examples/msg/msg_test.c
+++ b/examples/msg/msg_test.c
@@ -5,8 +5,16 @@
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
 
+/** \file msg_test.c 
+ *  \ingroup MSG_examples
+ *  \brief Simulation of a master-slave application using a realistic platform 
+ *  and an external description of the deployment.
+*/
+
+/** Yeah! If you want to use msg, you need to include msg/msg.h */
 #include "msg/msg.h"
 
+/** This flag enable the debugging messages from #PRINT_DEBUG_MESSAGE() */
 #define VERBOSE
 #include "messages.h"
 
@@ -21,8 +29,11 @@ typedef enum {
   MAX_CHANNEL
 } channel_t;
 
-void print_args(int argc, char** argv);
-void print_args(int argc, char** argv)
+/** Print arguments
+ * This function is just used so that users can check that each process
+ *  has received the arguments it was supposed to receive.
+ */
+static void print_args(int argc, char** argv)
 {
   int i ; 
 
@@ -32,6 +43,21 @@ void print_args(int argc, char** argv)
   fprintf(stderr,">\n");
 }
 
+/** Emitter function
+ * 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_launch_application().
+ 
+   C style arguments (argc/argv) are interpreted as 
+   \li the number of tasks to distribute
+   \li the computation size of each task
+   \li the size of the files associated to each task
+   \li a list of host that will accept those tasks.
+
+   Tasks are dumbly sent in a round-robin style.
+  */
 int master(int argc, char *argv[])
 {
   int slaves_count = 0;
@@ -101,6 +127,12 @@ int master(int argc, char *argv[])
   return 0;
 }
 
+/** Receiver function
+ * This function has to be assigned to a #m_process_t that has to behave as a slave.
+   Just like #master(), it should not be called directly.
+
+   This function keeps waiting for tasks and executes them as it receives them.
+  */
 int slave(int argc, char *argv[])
 {
   print_args(argc,argv);
@@ -124,7 +156,15 @@ int slave(int argc, char *argv[])
   return 0;
 }
 
+/** Receiver function
+ * This function has to be assigned to a #m_process_t that has to behave as a forwarder.
+   Just like #master(), it should not be called directly.
 
+   C style arguments (argc/argv) are interpreted as a list of host
+   that will accept those tasks.
+
+   This function keeps waiting for tasks and dispathes them to its slaves.
+  */
 int forwarder(int argc, char *argv[])
 {
   int i;
@@ -169,6 +209,19 @@ int forwarder(int argc, char *argv[])
 }
 
 
+/** Test function
+ * 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()
+ * @param platform_file the name of a file containing an valid surfxml platform 
+ *        description.
+ * @param application_file the name of a file containing a valid surfxml application 
+ *        description
+ */
 void test_all(const char *platform_file,const char *application_file)
 {
   {				/*  Simulation setting */
@@ -185,6 +238,11 @@ void test_all(const char *platform_file,const char *application_file)
   printf("Simulation time %Lg\n",MSG_getClock());
 }
 
+
+/** Main function
+ * This initializes MSG, runs a simulation, and free all data-structures created 
+ * by MSG.
+ */
 int main(int argc, char *argv[])
 {
   MSG_global_init_args(&argc,argv);