better presentation of the examples in the doc

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 75a24f4..77e7e45 100644 (file)
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -695,12 +695,7 @@ INPUT                  = doxygen/index.doc \
 ##  PLEASE DON'T MESS WITH THE ORDER OF EXAMPLES ## (unless you know what you are doing, of course)
 ###################################################
 
 ##  PLEASE DON'T MESS WITH THE ORDER OF EXAMPLES ## (unless you know what you are doing, of course)
 ###################################################
 

-INPUT +=                 @CMAKE_HOME_DIRECTORY@/examples/msg/app-pingpong/app-pingpong.c \
-                         @CMAKE_HOME_DIRECTORY@/examples/msg/app-token-ring/app-token-ring.c \
-                         @CMAKE_HOME_DIRECTORY@/examples/msg/app-masterworker/app-masterworker.c \
-                         @CMAKE_HOME_DIRECTORY@/examples/msg/async-wait/async-wait.c \
-                         @CMAKE_HOME_DIRECTORY@/examples/msg/async-waitall/async-waitall.c \
-                         @CMAKE_HOME_DIRECTORY@/examples/msg/async-waitany/async-waitany.c \
+INPUT +=                 @CMAKE_HOME_DIRECTORY@/examples/msg/README.doc \

                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-suspend/process-suspend.c \
                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-kill/process-kill.c \
                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-migration/process-migration.c \
                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-suspend/process-suspend.c \
                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-kill/process-kill.c \
                          @CMAKE_HOME_DIRECTORY@/examples/msg/process-migration/process-migration.c \

diff --git a/doc/Layout.xml b/doc/Layout.xml
index e7c5733..29d52d6 100644 (file)
--- a/doc/Layout.xml
+++ b/doc/Layout.xml
@@ -8,6 +8,7 @@
       <tab type="namespaces" visible="no" title="">
         <tab type="namespaces" visible="yes" title="" intro=""/>
       </tab>
       <tab type="namespaces" visible="no" title="">
         <tab type="namespaces" visible="yes" title="" intro=""/>
       </tab>

+      <tab type="examples" visible="yes" title="" intro=""/>  

       <tab type="classes" visible="no" title="">
         <tab type="classes" visible="yes" title="" intro=""/>
         <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
       <tab type="classes" visible="no" title="">
         <tab type="classes" visible="yes" title="" intro=""/>
         <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 

diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc
index 67cf686..71851e2 100644 (file)
--- a/doc/doxygen/module-msg.doc
+++ b/doc/doxygen/module-msg.doc
@@ -145,31 +145,3 @@ simulated process.
 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 
  */
 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 
  */

-
-
-/**
-@defgroup MSG_examples MSG examples
-@ingroup MSG_API
-@brief .
-
-
-Finding the right example in examples/msg is sometimes difficult. This list aims at helping you to find the example from which you can learn what you want to.
-  - @ref msg_ex_basic
-  - @ref msg_ex_async
-  - @ref msg_ex_process
-  - @ref msg_ex_tracing
-  - @ref msg_ex_tracing_user_variables
-  - @ref msg_ex_models
-  - @ref msg_ex_io
-  - @ref msg_ex_actions
-  - @ref msg_ex_full_apps
-  - @ref msg_ex_misc
-
-\section msg_ex_basic Basic examples
-*/
-
-
-
-
-
-

diff --git a/examples/msg/CMakeLists.txt b/examples/msg/CMakeLists.txt
index 4b7ef75..d821cd0 100644 (file)
--- a/examples/msg/CMakeLists.txt
+++ b/examples/msg/CMakeLists.txt
@@ -45,7 +45,7 @@ foreach (file actions-comm actions-storage app-bittorrent app-chainsend app-mast
   set(xml_files    ${xml_files}     ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml)
 endforeach()
 
   set(xml_files    ${xml_files}     ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml)
 endforeach()
 

-set(txt_files    ${txt_files}     ${CMAKE_CURRENT_SOURCE_DIR}/README
+set(txt_files    ${txt_files}     ${CMAKE_CURRENT_SOURCE_DIR}/README.doc

                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm.txt
                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm_split_p0.txt
                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm_split_p1.txt
                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm.txt
                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm_split_p0.txt
                                   ${CMAKE_CURRENT_SOURCE_DIR}/actions-comm/actions-comm_split_p1.txt

diff --git a/examples/msg/README b/examples/msg/README.doc
similarity index 58%
rename from examples/msg/README
rename to examples/msg/README.doc
index 5bebc7a..0eaa34f 100644 (file)
--- a/examples/msg/README
+++ b/examples/msg/README.doc
@@ -1,28 +1,90 @@
 This file follows the Doxygen syntax to be included in the documentation.
 
 /** 
 This file follows the Doxygen syntax to be included in the documentation.
 
 /** 

-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.
+ @defgroup MSG_examples MSG examples
+ @ingroup MSG_API
+ @brief Find the MSG example fitting your needs from the extensive set provided in the archive.
+
+  - @ref msg_ex_basic
+  - @ref msg_ex_async
+  - @ref msg_ex_process
+  - @ref msg_ex_tracing
+  - @ref msg_ex_tracing_user_variables
+  - @ref msg_ex_models
+  - @ref msg_ex_io
+  - @ref msg_ex_actions
+  - @ref msg_ex_full_apps
+  - @ref msg_ex_misc
+                   
+@section msg_ex_basic Basic examples and features
+
+ - <b>Ping Pong</b>: @ref examples/msg/app-pingpong/app-pingpong.c\n
+   It's hard to think of a simpler example: it is just sending one
+   message back and forth.  
+   The tesh file laying in the directory show how to start the
+   simulator binary, enlighting how to pass options to the simulators
+   (as detailed in Section \ref options). 
+
+ - <b>Token Ring</b>.
+   @ref examples/msg/app-token-ring/app-token-ring.c\n
+   Classical communication pattern, where a token is exchanged
+   along a ring to reach every participant. 
+   The tesh file laying in the directory shows how to run the same
+   example on different virtual platforms.
+
+ - <b>Master Workers</b>.
+   @ref examples/msg/app-masterworker/app-masterworker.c\n
+   Another good old example, where one Master process has a bunch of
+   task to dispatch to a set of several Worker processes. It is fully
+   commented in @ref MSG_ex_master_worker.
+
+@section msg_ex_async Asynchronous communications
+
+In addition to the fully documented example of @ref
+MSG_ex_asynchronous_communications, there are several other examples
+shipped in the archive:
+  
+ - <b>Basic asynchronous communications</b>. 
+   @ref examples/msg/async-wait/async-wait.c \n
+   Illustrates how to have non-blocking communications, that are
+   communications running in the background leaving the process free
+   to do something else during their completion. The main functions
+   involved are @ref MSG_task_isend, @ref MSG_task_irecv, and @ref
+   MSG_comm_wait.
+ 
+ - <b>Waiting for all communications in a set</b>.
+   @ref examples/msg/async-waitall/async-waitall.c\n
+   The @ref MSG_comm_waitall function is useful when you want to block
+   until all activities in a given set have completed.
+   
+ - <b>Waiting for the first completed communication in a set</b>.
+   @ref examples/msg/async-waitall/async-waitany.c\n
+   The @ref MSG_comm_waitany function is useful when you want to block
+   until one activity of the set completes, no matter which terminates
+   first.
+
+*/
+
+As a human, you can stop reading at this point. The rest is garbage:
+
+Every example must be listed in the following, but it's not possible
+to move this content upper as each example directive seems to eat the
+next doxygen commands. 
+
+
+/**
+@defgroup MSG_ex_examples ignored
+@example examples/msg/app-pingpong/app-pingpong.c        
+@example examples/msg/app-token-ring/app-token-ring.c    
+@example examples/msg/app-masterworker/app-masterworker.c
+
+@example examples/msg/async-wait/async-wait.c
+@example examples/msg/async-waitall/async-waitall.c
+@example examples/msg/async-waitall/async-waitany.c
+*/

 
 Basic examples and features
 ===========================
 
 Basic examples and features
 ===========================

- * sendrecv/sendrecv.c: Ping-pong example. It's hard to think of a
-   simpler example. The tesh files laying in the directory are
-   instructive concerning the way to pass options to the simulators
-   (as described in "Simgrid options and configurations").
-
- * masterslave/masterslave_forwarder.c: Master/slaves example. This
-   good old example is also very simple. Its basic version is fully
-   commented in the web documentation, but several variants can be
-   found in the same directory.
-
- * masterslave/masterslave_console.c: demonstrate how to use lua files
-   instead of XML for the platform and deployment declaration using
-   MSG_load_platform_script(). The most interesting part is probably
-   not the C code, but rather the masterslave/masterslave_script.lua,
-   which demonstrates how to express the platform and deployment in
-   lua.

 
  * migration/migration.c Demonstrates how to use the
    MSG_process_migrate() function to let processes change the host
 
  * migration/migration.c Demonstrates how to use the
    MSG_process_migrate() function to let processes change the host


@@ -49,17 +111,6 @@ Basic examples and features
    MSG_task_set_priority() to change the computation priority of a
    given task.
 
    MSG_task_set_priority() to change the computation priority of a
    given task.
 

-Asynchronous communications
-===========================
-There is several examples of asynchronous communications coming in the
-archive. In addition to the fully documented example [50]Asynchronous
-communications, there is several other examples in the archive:
-   
- * msg/icomms/peer.c: basic example of async functions
-   (MSG_task_isend, MSG_task_irecv, MSG_comm_wait)
- * msg/icomms/peer2.c: demonstrates the MSG_comm_waitall() function
- * msg/icomms/peer3.c: demonstrates the MSG_comm_waitany() function
-

 Tracing and visualization features
 ==================================
  * tracing/simple.c very simple program that creates, executes and
 Tracing and visualization features
 ==================================
  * tracing/simple.c very simple program that creates, executes and


@@ -123,14 +174,6 @@ probably be changed to use SMPI internals instead, but wasn't, so far.
 Examples of full applications
 =============================
 
 Examples of full applications
 =============================
 

- * token_ring/ring_call.c: Classical token ring communication, where a
-   token is exchanged along a ring to reach every participant.
-
- * pmm/msg_pmm.c: Parallel Matrix Multiplication is a little
-   application. This is something that most MPI developper have
-   written during their class, here implemented using MSG instead of
-   MPI.
-

  * chord/chord.c: Classical Chord P2P protocol This example implements
    the well known Chord P2P protocol. Its main advantage is that it
    constitute a fully working non-trivial example. In addition, its
  * chord/chord.c: Classical Chord P2P protocol This example implements
    the well known Chord P2P protocol. Its main advantage is that it
    constitute a fully working non-trivial example. In addition, its


@@ -138,4 +181,3 @@ Examples of full applications
    [57]http://hal.inria.fr/inria-00602216/
 
 
    [57]http://hal.inria.fr/inria-00602216/
 
 

-*/
\ No newline at end of file

diff --git a/examples/msg/app-masterworker/app-masterworker.c b/examples/msg/app-masterworker/app-masterworker.c
index 8780b23..0640633 100644 (file)
--- a/examples/msg/app-masterworker/app-masterworker.c
+++ b/examples/msg/app-masterworker/app-masterworker.c
@@ -1,5 +1,4 @@
-/* Copyright (c) 2010-2015. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2010-2016. The SimGrid Team. All rights reserved.          */

 
 /* 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. */
 
 /* 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. */


@@ -8,39 +7,34 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_app_masterworker, "Messages specific for this msg example");
 
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_app_masterworker, "Messages specific for this msg example");
 

-/** @addtogroup MSG_examples
- *
- *  - <b>Master/Workers: app-masterworker/app-masterworker.c</b>. This good old example is also very simple. Its
- *    basic version is fully commented on this page: \ref MSG_ex_master_worker.
- */

 
 

-/** @brief Master expects 4 arguments given in the XML deployment file: */
+/* Main function of the master process. It expects 4 arguments given in the XML deployment file: */

 static int master(int argc, char *argv[])
 {
 static int master(int argc, char *argv[])
 {

-  long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");    /** - Number of tasks      */
-  double comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s");  /** - Task compute cost    */
-  double comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s");  /** - Task communication size */
-  long workers_count = xbt_str_parse_int(argv[4], "Invalid amount of workers: %s");    /** - Number of workers    */
+  long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");    /* - Number of tasks      */
+  double comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s");  /* - Task compute cost    */
+  double comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s");  /* - Task communication size */
+  long workers_count = xbt_str_parse_int(argv[4], "Invalid amount of workers: %s");    /* - Number of workers    */

 
   int i;
 
   XBT_INFO("Got %ld workers and %ld tasks to process", workers_count, number_of_tasks);
 
 
   int i;
 
   XBT_INFO("Got %ld workers and %ld tasks to process", workers_count, number_of_tasks);
 

-  for (i = 0; i < number_of_tasks; i++) {  /** For each task to be executed: */
+  for (i = 0; i < number_of_tasks; i++) {  /* For each task to be executed: */

     char mailbox[256];
     char task_name[256];
 
     char mailbox[256];
     char task_name[256];
 

-    sprintf(mailbox, "worker-%ld", i % workers_count); /** - Select a @ref worker in a round-robin way */
+    sprintf(mailbox, "worker-%ld", i % workers_count); /* - Select a @ref worker in a round-robin way */

     sprintf(task_name, "Task_%d", i);
     sprintf(task_name, "Task_%d", i);

-    msg_task_t task = MSG_task_create(task_name, comp_size, comm_size, NULL);   /** - Create a task */
+    msg_task_t task = MSG_task_create(task_name, comp_size, comm_size, NULL);   /* - Create a task */

     if (number_of_tasks < 10000 || i % 10000 == 0)
       XBT_INFO("Sending \"%s\" (of %ld) to mailbox \"%s\"", task->name, number_of_tasks, mailbox);
 
     if (number_of_tasks < 10000 || i % 10000 == 0)
       XBT_INFO("Sending \"%s\" (of %ld) to mailbox \"%s\"", task->name, number_of_tasks, mailbox);
 

-    MSG_task_send(task, mailbox); /** - Send the task to the @ref worker */
+    MSG_task_send(task, mailbox); /* - Send the task to the @ref worker */

   }
 
   XBT_INFO("All tasks have been dispatched. Let's tell everybody the computation is over.");
   }
 
   XBT_INFO("All tasks have been dispatched. Let's tell everybody the computation is over.");

-  for (i = 0; i < workers_count; i++) { /** - Eventually tell all the workers to stop by sending a "finalize" task */
+  for (i = 0; i < workers_count; i++) { /* - Eventually tell all the workers to stop by sending a "finalize" task */

     char mailbox[80];
 
     sprintf(mailbox, "worker-%ld", i % workers_count);
     char mailbox[80];
 
     sprintf(mailbox, "worker-%ld", i % workers_count);


@@ -51,7 +45,7 @@ static int master(int argc, char *argv[])
   return 0;
 }
 
   return 0;
 }
 

-/** @brief Worker expects a single argument given in the XML deployment file: */
+/* Main functions of the Worker processes. It expects a single argument given in the XML deployment file: the unique ID of the worker. */

 static int worker(int argc, char *argv[])
 {
   msg_task_t task = NULL;
 static int worker(int argc, char *argv[])
 {
   msg_task_t task = NULL;


@@ -59,19 +53,19 @@ static int worker(int argc, char *argv[])
 
   long id= xbt_str_parse_int(argv[1], "Invalid argument %s");
 
 
   long id= xbt_str_parse_int(argv[1], "Invalid argument %s");
 

-  sprintf(mailbox, "worker-%ld", id); /** - unique id of the worker */
+  sprintf(mailbox, "worker-%ld", id);

 
 

-  while (1) {  /** The worker wait in an infinite loop for tasks sent by the \ref master */
+  while (1) {  /* The worker wait in an infinite loop for tasks sent by the \ref master */

     int res = MSG_task_receive(&(task), mailbox);
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
 
 //  XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
     if (!strcmp(MSG_task_get_name(task), "finalize")) {
     int res = MSG_task_receive(&(task), mailbox);
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
 
 //  XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
     if (!strcmp(MSG_task_get_name(task), "finalize")) {

-      MSG_task_destroy(task);  /** - Exit if 'finalize' is received */
+      MSG_task_destroy(task);  /* - Exit if 'finalize' is received */

       break;
     }
 //    XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));
       break;
     }
 //    XBT_INFO("Processing \"%s\"", MSG_task_get_name(task));

-    MSG_task_execute(task);    /**  - Otherwise, process the task */
+    MSG_task_execute(task);    /*  - Otherwise, process the task */

 //    XBT_INFO("\"%s\" done", MSG_task_get_name(task));
     MSG_task_destroy(task);
     task = NULL;
 //    XBT_INFO("\"%s\" done", MSG_task_get_name(task));
     MSG_task_destroy(task);
     task = NULL;


@@ -86,13 +80,13 @@ int main(int argc, char *argv[])
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]);
 
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]);
 

-  MSG_create_environment(argv[1]);          /** - Load the platform description */
+  MSG_create_environment(argv[1]);          /* - Load the platform description */

 
 

-  MSG_function_register("master", master);  /** - Register the function to be executed by the processes */
+  MSG_function_register("master", master);  /* - Register the function to be executed by the processes */

   MSG_function_register("worker", worker);
   MSG_function_register("worker", worker);

-  MSG_launch_application(argv[2]);          /** - Deploy the application */
+  MSG_launch_application(argv[2]);          /* - Deploy the application */

 
 

-  msg_error_t res = MSG_main();             /** - Run the simulation */
+  msg_error_t res = MSG_main();             /* - Run the simulation */

 
   XBT_INFO("Simulation time %g", MSG_get_clock());
 
 
   XBT_INFO("Simulation time %g", MSG_get_clock());
 

diff --git a/examples/msg/app-pingpong/app-pingpong.c b/examples/msg/app-pingpong/app-pingpong.c
index acef93a..4580840 100644 (file)
--- a/examples/msg/app-pingpong/app-pingpong.c
+++ b/examples/msg/app-pingpong/app-pingpong.c
@@ -6,14 +6,6 @@
 
 #include "simgrid/msg.h"
 
 
 #include "simgrid/msg.h"
 

-/** @addtogroup MSG_examples
- *
- *  @example app-pingpong/app-pingpong.c
- * 
- *  - <b>Ping-Pong: app-pingpong/app-pingpong.c</b>. It's hard to think of a simpler example. The tesh file
- *    laying in the directory is instructive concerning the way to pass options to the simulators (see \ref options).
- */
-

 XBT_LOG_NEW_DEFAULT_CATEGORY(mag_app_pingpong,"Messages specific for this msg example");
 
 static int pinger(int argc, char *argv[])
 XBT_LOG_NEW_DEFAULT_CATEGORY(mag_app_pingpong,"Messages specific for this msg example");
 
 static int pinger(int argc, char *argv[])


@@ -48,7 +40,7 @@ static int ponger(int argc, char *argv[])
   XBT_INFO("Pong -> %s", argv[1]);
   xbt_assert(MSG_host_by_name(argv[1]) != NULL, "Unknown host %s. Stopping Now! ", argv[1]);
 
   XBT_INFO("Pong -> %s", argv[1]);
   xbt_assert(MSG_host_by_name(argv[1]) != NULL, "Unknown host %s. Stopping Now! ", argv[1]);
 

-  /** - Receive the (small) ping first ....*/
+  /* - Receive the (small) ping first ....*/

   msg_task_t ping_task = NULL;
   int a = MSG_task_receive(&ping_task, MSG_host_get_name(MSG_host_self()));
   xbt_assert(a == MSG_OK, "Unexpected behavior");
   msg_task_t ping_task = NULL;
   int a = MSG_task_receive(&ping_task, MSG_host_get_name(MSG_host_self()));
   xbt_assert(a == MSG_OK, "Unexpected behavior");


@@ -60,7 +52,7 @@ static int ponger(int argc, char *argv[])
   MSG_task_destroy(ping_task);
   XBT_INFO(" Ping time (latency bound) %e", communication_time);
 
   MSG_task_destroy(ping_task);
   XBT_INFO(" Ping time (latency bound) %e", communication_time);
 

-  /**  - ... Then send a 1GB pong back (bandwidth bound) */
+  /*  - ... Then send a 1GB pong back (bandwidth bound) */

   double time = MSG_get_clock();
   msg_task_t pong_task = MSG_task_create("large communication (bandwidth bound)", 0.0, 1e9, NULL);
   pong_task->data = xbt_new(double, 1);
   double time = MSG_get_clock();
   msg_task_t pong_task = MSG_task_create("large communication (bandwidth bound)", 0.0, 1e9, NULL);
   pong_task->data = xbt_new(double, 1);


@@ -80,14 +72,14 @@ int main(int argc, char *argv[])
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s ../../platform/small_platform.xml app-pingpong_d.xml\n", argv[0], argv[0]);
 
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s ../../platform/small_platform.xml app-pingpong_d.xml\n", argv[0], argv[0]);
 

-  MSG_create_environment(argv[1]);          /** - Load the platform description */
+  MSG_create_environment(argv[1]);          /* - Load the platform description */

 
 

-  MSG_function_register("pinger", pinger);  /** - Register the function to be executed by the processes */
+  MSG_function_register("pinger", pinger);  /* - Register the function to be executed by the processes */

   MSG_function_register("ponger", ponger);
 
   MSG_function_register("ponger", ponger);
 

-  MSG_launch_application(argv[2]);          /** - Deploy the application */
+  MSG_launch_application(argv[2]);          /* - Deploy the application */

 
 

-  res = MSG_main();                         /** - Run the simulation */
+  res = MSG_main();                         /* - Run the simulation */

 
   XBT_INFO("Total simulation time: %e", MSG_get_clock());
   return res!=MSG_OK;
 
   XBT_INFO("Total simulation time: %e", MSG_get_clock());
   return res!=MSG_OK;

diff --git a/examples/msg/app-token-ring/app-token-ring.c b/examples/msg/app-token-ring/app-token-ring.c
index de7e757..abe1691 100644 (file)
--- a/examples/msg/app-token-ring/app-token-ring.c
+++ b/examples/msg/app-token-ring/app-token-ring.c
@@ -1,5 +1,4 @@
-/* Copyright (c) 2008-2015. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2008-2016. The SimGrid Team. All rights reserved.          */

 
 /* 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. */
 
 /* 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. */


@@ -8,22 +7,15 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_app_token_ring, "Messages specific for this msg example");
 
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_app_token_ring, "Messages specific for this msg example");
 

-/** @addtogroup MSG_examples
- * 
- * - <b>Token Ring: app-token-ring/app-token-ring.c</b>. Classical token ring communication, where a token is exchanged
- *   along a ring to reach every participant. The tesh file laying in the directory shows how to run the same example on
- *   different platforms.
- */
-
-/** Single function for all hosts */
+/* Main function of all processes used in this example */

 static int foo(int argc, char *argv[])
 {
 static int foo(int argc, char *argv[])
 {

-  unsigned int task_comm_size = 1000000; /** The token is 1MB long*/
-  int rank = xbt_str_parse_int(MSG_process_get_name(MSG_process_self()), "Invalid process name: %s");
+  unsigned int task_comm_size = 1000000; /* The token is 1MB long*/
+  int rank = xbt_str_parse_int(MSG_process_get_name(MSG_process_self()), "Any process of this example must have a numerical name, not %s");

   char mailbox[256];
   msg_task_t task = NULL;
   XBT_ATTRIB_UNUSED int res;
   char mailbox[256];
   msg_task_t task = NULL;
   XBT_ATTRIB_UNUSED int res;

-  if (rank == 0){ /** - The root (rank 0) first sends the token then waits to receive it back */
+  if (rank == 0){ /* - The root (rank 0) first sends the token then waits to receive it back */

     sprintf(mailbox, "%d", rank+1);
     task = MSG_task_create("Token", 0, task_comm_size, NULL);
     XBT_INFO("Host \"%d\" send '%s' to Host \"%s\"", rank, task->name,mailbox);
     sprintf(mailbox, "%d", rank+1);
     task = MSG_task_create("Token", 0, task_comm_size, NULL);
     XBT_INFO("Host \"%d\" send '%s' to Host \"%s\"", rank, task->name,mailbox);


@@ -33,12 +25,12 @@ static int foo(int argc, char *argv[])
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
     XBT_INFO("Host \"%d\" received \"%s\"", rank, MSG_task_get_name(task));
     MSG_task_destroy(task);
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
     XBT_INFO("Host \"%d\" received \"%s\"", rank, MSG_task_get_name(task));
     MSG_task_destroy(task);

-  } else{ /** - The others receive from their left neighbor (rank-1) and send to their right neighbor (rank+1) */
+  } else{ /* - The others receive from their left neighbor (rank-1) and send to their right neighbor (rank+1) */

     res = MSG_task_receive(&(task), MSG_process_get_name(MSG_process_self()));
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
     XBT_INFO("Host \"%d\" received \"%s\"",rank, MSG_task_get_name(task));
 
     res = MSG_task_receive(&(task), MSG_process_get_name(MSG_process_self()));
     xbt_assert(res == MSG_OK, "MSG_task_get failed");
     XBT_INFO("Host \"%d\" received \"%s\"",rank, MSG_task_get_name(task));
 

-    if(rank+1 == MSG_get_host_number()) /** - Except for the last one which sends the token back to rank 0 */
+    if(rank+1 == MSG_get_host_number()) /* - Except for the last one which sends the token back to rank 0 */

       sprintf(mailbox, "0");
     else
       sprintf(mailbox, "%d", rank+1);
       sprintf(mailbox, "0");
     else
       sprintf(mailbox, "%d", rank+1);


@@ -52,19 +44,19 @@ int main(int argc, char *argv[])
 {
   unsigned int i;
   MSG_init(&argc, argv);
 {
   unsigned int i;
   MSG_init(&argc, argv);

-  MSG_create_environment(argv[1]);       /** - Load the platform description */
+  MSG_create_environment(argv[1]);       /* - Load the platform description */

   xbt_dynar_t hosts = MSG_hosts_as_dynar();
   msg_host_t h;
 
   XBT_INFO("Number of host '%d'",MSG_get_host_number());
   xbt_dynar_t hosts = MSG_hosts_as_dynar();
   msg_host_t h;
 
   XBT_INFO("Number of host '%d'",MSG_get_host_number());

-  xbt_dynar_foreach (hosts, i, h){      /** - Give a unique rank to each host and create a @ref foo process on each */
+  xbt_dynar_foreach (hosts, i, h){      /* - Give a unique rank to each host and create a @ref foo process on each */

     char* name_host = bprintf("%u",i);
     MSG_process_create(name_host, foo, NULL, h);
     free(name_host);
   }
   xbt_dynar_free(&hosts);
 
     char* name_host = bprintf("%u",i);
     MSG_process_create(name_host, foo, NULL, h);
     free(name_host);
   }
   xbt_dynar_free(&hosts);
 

-  int res = MSG_main();                 /** - Run the simulation */
+  int res = MSG_main();                 /* - Run the simulation */

   XBT_INFO("Simulation time %g", MSG_get_clock());
   return res != MSG_OK;
 }
   XBT_INFO("Simulation time %g", MSG_get_clock());
   return res != MSG_OK;
 }

diff --git a/examples/msg/async-wait/async-wait.c b/examples/msg/async-wait/async-wait.c
index a6dc316..da753e8 100644 (file)
--- a/examples/msg/async-wait/async-wait.c
+++ b/examples/msg/async-wait/async-wait.c
@@ -1,5 +1,4 @@
-/* Copyright (c) 2010-2015. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2010-2016. The SimGrid Team. All rights reserved.          */

 
 /* 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. */
 
 /* 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. */


@@ -8,26 +7,15 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_wait, "Messages specific for this msg example");
 
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_wait, "Messages specific for this msg example");
 

-/** @addtogroup MSG_examples
- * 
- * @section msg_ex_async Asynchronous communications
- * 
- * In addition to the fully documented example of \ref MSG_ex_asynchronous_communications, there are several other
- * examples shipped in the archive:
- * 
- * - <b>Basic example: async-wait/async-wait.c</b>. Illustrates the use of asynchronous functions (@ref MSG_task_isend,
- *    @ref MSG_task_irecv, and @ref MSG_comm_wait).
- */
-
-/** Sender process expects 6 arguments: */
+/* Sender process expects 6 arguments: */

 static int sender(int argc, char *argv[])
 {
 static int sender(int argc, char *argv[])
 {

-  long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");        /** - number of tasks */
-  double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s"); /** - computational cost */
-  double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s"); /** - communication cost */
-  long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s");    /** - number of receivers */
-  double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s"); /** - start time */
-  double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s");         /** - test time */
+  long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");        /* - number of tasks */
+  double task_comp_size = xbt_str_parse_double(argv[2], "Invalid computational size: %s"); /* - computational cost */
+  double task_comm_size = xbt_str_parse_double(argv[3], "Invalid communication size: %s"); /* - communication cost */
+  long receivers_count = xbt_str_parse_int(argv[4], "Invalid amount of receivers: %s");    /* - number of receivers */
+  double sleep_start_time = xbt_str_parse_double(argv[5], "Invalid sleep start time: %s"); /* - start time */
+  double sleep_test_time = xbt_str_parse_double(argv[6], "Invalid test time: %s");         /* - test time */

 
   XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
 
 
   XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
 


@@ -42,15 +30,15 @@ static int sender(int argc, char *argv[])
     sprintf(mailbox, "receiver-%ld", i % receivers_count);
     sprintf(sprintf_buffer, "Task_%d", i);
 
     sprintf(mailbox, "receiver-%ld", i % receivers_count);
     sprintf(sprintf_buffer, "Task_%d", i);
 

-    /** This process first creates a task and send it asynchronously with @ref MSG_task_isend. Then, if: */
+    /* This process first creates a task and send it asynchronously with @ref MSG_task_isend. Then, if: */

     task = MSG_task_create(sprintf_buffer, task_comp_size, task_comm_size, NULL);
     comm = MSG_task_isend(task, mailbox);
     XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i);
 
     task = MSG_task_create(sprintf_buffer, task_comp_size, task_comm_size, NULL);
     comm = MSG_task_isend(task, mailbox);
     XBT_INFO("Send to receiver-%ld Task_%d", i % receivers_count, i);
 

-    if (sleep_test_time == 0) { /** - "test_time" is set to 0, wait on @ref MSG_comm_wait */
+    if (sleep_test_time == 0) { /* - "test_time" is set to 0, wait on @ref MSG_comm_wait */

       MSG_comm_wait(comm, -1);
     } else {
       MSG_comm_wait(comm, -1);
     } else {

-      while (MSG_comm_test(comm) == 0) { /** - Call @ref MSG_comm_test every "test_time" otherwise */
+      while (MSG_comm_test(comm) == 0) { /* - Call @ref MSG_comm_test every "test_time" otherwise */

         MSG_process_sleep(sleep_test_time);
       };
     }
         MSG_process_sleep(sleep_test_time);
       };
     }


@@ -77,42 +65,42 @@ static int sender(int argc, char *argv[])
   return 0;
 }
 
   return 0;
 }
 

-/** Receiver process expects 3 arguments: */
+/* Receiver process expects 3 arguments: */

 static int receiver(int argc, char *argv[])
 {
   msg_task_t task = NULL;
   XBT_ATTRIB_UNUSED msg_error_t res;
   char mailbox[80];
   msg_comm_t res_irecv;
 static int receiver(int argc, char *argv[])
 {
   msg_task_t task = NULL;
   XBT_ATTRIB_UNUSED msg_error_t res;
   char mailbox[80];
   msg_comm_t res_irecv;

-  int id = xbt_str_parse_int(argv[1], "Invalid id: %s");                                        /** - unique id */
-  double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s"); /** - start time */
-  double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s");   /** - test time */
+  int id = xbt_str_parse_int(argv[1], "Invalid id: %s");                                        /* - unique id */
+  double sleep_start_time = xbt_str_parse_double(argv[2], "Invalid sleep start parameter: %s"); /* - start time */
+  double sleep_test_time = xbt_str_parse_double(argv[3], "Invalid sleep test parameter: %s");   /* - test time */

   XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
 
   XBT_INFO("sleep_start_time : %f , sleep_test_time : %f", sleep_start_time, sleep_test_time);
 

-  MSG_process_sleep(sleep_start_time); /** This process first sleeps for "start time" seconds.  */
+  MSG_process_sleep(sleep_start_time); /* This process first sleeps for "start time" seconds.  */

 
   sprintf(mailbox, "receiver-%d", id);
   while (1) {
 
   sprintf(mailbox, "receiver-%d", id);
   while (1) {

-    res_irecv = MSG_task_irecv(&(task), mailbox); /** Then it posts asynchronous receives (@ref MSG_task_irecv) and*/
+    res_irecv = MSG_task_irecv(&(task), mailbox); /* Then it posts asynchronous receives (@ref MSG_task_irecv) and*/

     XBT_INFO("Wait to receive a task");
 
     XBT_INFO("Wait to receive a task");
 

-    if (sleep_test_time == 0) {               /** - if "test_time" is set to 0, wait on @ref MSG_comm_wait */
+    if (sleep_test_time == 0) {               /* - if "test_time" is set to 0, wait on @ref MSG_comm_wait */

       res = MSG_comm_wait(res_irecv, -1);
       xbt_assert(res == MSG_OK, "MSG_task_get failed");
     } else {
       res = MSG_comm_wait(res_irecv, -1);
       xbt_assert(res == MSG_OK, "MSG_task_get failed");
     } else {

-      while (MSG_comm_test(res_irecv) == 0) { /** - Call @ref MSG_comm_test every "test_time" otherwise */
+      while (MSG_comm_test(res_irecv) == 0) { /* - Call @ref MSG_comm_test every "test_time" otherwise */

         MSG_process_sleep(sleep_test_time);
       };
     }
     MSG_comm_destroy(res_irecv);
 
     XBT_INFO("Received \"%s\"", MSG_task_get_name(task));
         MSG_process_sleep(sleep_test_time);
       };
     }
     MSG_comm_destroy(res_irecv);
 
     XBT_INFO("Received \"%s\"", MSG_task_get_name(task));

-    if (!strcmp(MSG_task_get_name(task), "finalize")) { /** If the received task is "finalize", the process ends */
+    if (!strcmp(MSG_task_get_name(task), "finalize")) { /* If the received task is "finalize", the process ends */

       MSG_task_destroy(task);
       break;
     }
 
       MSG_task_destroy(task);
       break;
     }
 

-    XBT_INFO("Processing \"%s\"", MSG_task_get_name(task)); /** Otherwise, the task is processed */
+    XBT_INFO("Processing \"%s\"", MSG_task_get_name(task)); /* Otherwise, the task is processed */

     MSG_task_execute(task);
     XBT_INFO("\"%s\" done", MSG_task_get_name(task));
     MSG_task_destroy(task);
     MSG_task_execute(task);
     XBT_INFO("\"%s\" done", MSG_task_get_name(task));
     MSG_task_destroy(task);


@@ -130,13 +118,13 @@ int main(int argc, char *argv[])
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]);
 
   xbt_assert(argc > 2, "Usage: %s platform_file deployment_file\n"
              "\tExample: %s msg_platform.xml msg_deployment.xml\n", argv[0], argv[0]);
 

-  MSG_create_environment(argv[1]);/** - Load the platform description */
+  MSG_create_environment(argv[1]);/* - Load the platform description */

 
   MSG_function_register("sender", sender);
   MSG_function_register("receiver", receiver);
 
   MSG_function_register("sender", sender);
   MSG_function_register("receiver", receiver);

-  MSG_launch_application(argv[2]);/** - Deploy the @ref sender and @ref receiver processes */
+  MSG_launch_application(argv[2]);/* - Deploy the sender and receiver processes */

 
 

-  res = MSG_main();  /** - Run the simulation */
+  res = MSG_main();  /* - Run the simulation */

 
   XBT_INFO("Simulation time %g", MSG_get_clock());
 
 
   XBT_INFO("Simulation time %g", MSG_get_clock());
 

diff --git a/examples/msg/async-waitall/async-waitall.c b/examples/msg/async-waitall/async-waitall.c
index bc3db3b..6c3848e 100644 (file)
--- a/examples/msg/async-waitall/async-waitall.c
+++ b/examples/msg/async-waitall/async-waitall.c
@@ -1,5 +1,4 @@
-/* Copyright (c) 2010-2015. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2010-2016. The SimGrid Team. All rights reserved.          */

 
 /* 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. */
 
 /* 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. */


@@ -8,11 +7,6 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitall, "Messages specific for this msg example");
 
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitall, "Messages specific for this msg example");
 

-/** @addtogroup MSG_examples
- * 
- * - <b>Wait all: async-waitall/async-waitall.c</b>. Illustrates the use of the @ref MSG_comm_waitall function.
- */
-

 static int sender(int argc, char *argv[])
 {
   long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");
 static int sender(int argc, char *argv[])
 {
   long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");

diff --git a/examples/msg/async-waitany/async-waitany.c b/examples/msg/async-waitany/async-waitany.c
index 4e053e4..d185701 100644 (file)
--- a/examples/msg/async-waitany/async-waitany.c
+++ b/examples/msg/async-waitany/async-waitany.c
@@ -1,5 +1,4 @@
-/* Copyright (c) 2010-2015. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2010-2016. The SimGrid Team. All rights reserved.          */

 
 /* 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. */
 
 /* 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. */


@@ -8,11 +7,6 @@
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitany, "Messages specific for this msg example");
 
 
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_async_waitany, "Messages specific for this msg example");
 

-/** @addtogroup MSG_examples
- *
- * - <b>Wait any: async-waitany/async-waitany.c</b>. Illustrates the use of the @ref MSG_comm_waitany function.
- */
-

 static int sender(int argc, char *argv[])
 {
   long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");
 static int sender(int argc, char *argv[])
 {
   long number_of_tasks = xbt_str_parse_int(argv[1], "Invalid amount of tasks: %s");