doc/doxygen/examples.doc

   1 /*! \page examples SimGrid Examples
   2
   3 \tableofcontents
   4
   5 SimGrid comes with many examples provided in the examples/ directory.
   6 Those examples are described in section \ref msg_examples. Those
   7 examples are commented and should be easy to understand. for a first
   8 step into SimGrid we also provide some more detailed examples in the
   9 sections below.
  10
  11 \htmlonly
  12 You should also check our online <a href="http://simgrid.gforge.inria.fr/documentation.html"> tutorial section</a> that contains a generic tutorial about using SimGrid.
  13 \endhtmlonly
  14
  15 \section using_msg Using MSG
  16
  17 \htmlonly
  18 You should also check our online <a href="http://simgrid.gforge.inria.fr/documentation.html"> tutorial section</a> that contains a dedicated tutorial.
  19 \endhtmlonly
  20
  21 Here are some examples on how to use MSG, the most used API.
  22
  23 MSG comes with an extensive set of examples. It is sometimes difficult
  24 to find the one you need. This list aims at helping you finding the
  25 example from which you can learn what you want to.
  26
  27 \subsection MSG_ex_basics Basic examples and features
  28
  29 \subsubsection MSG_ex_master_worker Basic Master/Workers
  30
  31 Simulation of a master-worker application using a realistic platform and an external description of the deployment.
  32
  33 \paragraph MSG_ex_mw_TOC Table of contents:
  34
  35    - \ref MSG_ext_mw_preliminary
  36    - \ref MSG_ext_mw_master
  37    - \ref MSG_ext_mw_worker
  38    - \ref MSG_ext_mw_core
  39      - \ref MSG_ext_mw_platform
  40      - \ref MSG_ext_mw_application
  41
  42 <hr>
  43
  44 \dontinclude msg/app-masterworker/app-masterworker.c
  45
  46 \paragraph MSG_ext_mw_preliminary Preliminary declarations
  47
  48 \skip include
  49 \until example");
  50 \skipline Master expects
  51
  52 \paragraph MSG_ext_mw_master Master code
  53
  54 This function has to be assigned to a #msg_process_t that will behave as the master. It should not be called directly
  55 but either given as a parameter to #MSG_process_create() or registered as a public function through
  56 #MSG_function_register() and then automatically assigned to a process through #MSG_launch_application().
  57
  58 C style arguments (argc/argv) are interpreted as:
  59    - the number of tasks to distribute
  60    - the computational size of each task
  61    - the communication size of each task
  62    - the number of workers managed by the master.
  63
  64 Tasks are evenly sent in a round-robin style.
  65
  66 \until return 0;
  67 \until }
  68 \skipline Worker expects
  69
  70 \paragraph MSG_ext_mw_worker Worker code
  71
  72 This function has to be assigned to a #msg_process_t that has to behave as a worker. Just like the master function
  73 (described in \ref MSG_ext_mw_master), it should not be called directly.
  74
  75 C style arguments (argc/argv) are interpreted as:
  76    - a unique id used to build the mailbox name of the worker
  77
  78 This function keeps waiting for tasks and executes them as it receives them. When a special task named 'finalize' is
  79 received from the master, the process ends its execution.
  80
  81 \until return 0;
  82 \until }
  83
  84 \paragraph MSG_ext_mw_core Main function
  85
  86 This function is the core of the simulation and is divided only into 3 parts:
  87    -# Simulation settings : #MSG_create_environment() creates a realistic
  88       environment
  89    -# Application deployment : create the processes on the right locations with
  90       #MSG_launch_application()
  91    -# The simulation is run with #MSG_main()
  92
  93 Its arguments are:
  94    - <i>platform_file</i>: the name of a file containing an valid platform description.
  95    - <i>deployment_file</i>: the name of a file containing a valid application description
  96 \line main
  97 \until OK;
  98 \until }
  99
 100 \paragraph MSG_ext_mw_platform Example of a platform file
 101
 102 The following platform description can be found in \c examples/msg/platforms/small_platform.xml
 103 \include platforms/small_platform.xml
 104
 105 \paragraph MSG_ext_mw_application Example of a deployment file
 106
 107 The following application description can be found in \c examples/msg/app-masterworker/app-masterworker_d.xml:
 108
 109 \include msg/app-masterworker/app-masterworker_d.xml
 110
 111 \subsubsection MSG_ex_asynchronous_communications Asynchronous communications
 112
 113 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
 114 an external description of the deployment.
 115
 116  - \ref MSG_ext_async_code
 117    - \ref MSG_ext_async_preliminary
 118    - \ref MSG_ext_async_Sender
 119    - \ref MSG_ext_async_Receiver
 120    - \ref MSG_ext_async_Main
 121  - \ref MSG_ext_async_fct_Waitall
 122  - \ref MSG_ext_async_fct_Waitany
 123
 124 <hr>
 125
 126 \dontinclude msg/async-wait/async-wait.c
 127
 128 \paragraph MSG_ext_async_code Code of the application
 129
 130 \paragraph MSG_ext_async_preliminary Preliminary declarations
 131 \skip include
 132 \until Sender
 133
 134 \paragraph MSG_ext_async_Sender Sender function
 135
 136 A host can send an asynchronous message with \c MSG_task_isend(). As this function is non-blocking, we have to call
 137 \c MSG_comm_test() to know if the communication is complete and evenetually destroy it with a call to
 138 \c MSG_comm_destroy(). It is also possible to call \c MSG_comm_wait() which provides a shortcut.
 139
 140   C style arguments (argc/argv) are interpreted as:
 141    - the number of tasks to distribute
 142    - the computation size of each task
 143    - the size of the files associated to each task
 144    - the number of receivers that will accept those tasks
 145    - the time to sleep at the beginning of the function. This time defines the process sleep time:
 146            - if time = 0, use MSG_comm_wait()
 147            - if time > 0, use MSG_comm_test()
 148
 149 \until Receiver
 150
 151 \paragraph MSG_ext_async_Receiver Receiver function
 152
 153 This function executes tasks when it receives them. As the receiving is asynchronous, we have to test the completion of
 154 the communication with \c MSG_comm_test() or wait for it with \c MSG_comm_wait().
 155
 156   C style arguments (argc/argv) are interpreted as:
 157    - the id to use for received the communication.
 158    - the time to sleep at the beginning of the function
 159    - This time defined the process sleep time
 160            - if time = 0 use of MSG_comm_wait()
 161            - if time > 0 use of MSG_comm_test()
 162
 163 \until return
 164 \until }
 165
 166 \paragraph MSG_ext_async_Main Main function
 167
 168 This function is the core of the simulation and is divided only into 3 parts:
 169      -# Simulation settings : MSG_create_environment() loads a platform description
 170      -# Application deployment : create the processes on the right locations with MSG_launch_application()
 171      -# The simulation is run with #MSG_main()
 172
 173   Its arguments are:
 174     - <i>platform_file</i>: the name of a file containing an valid platform description.
 175     - <i>application_file</i>: the name of a file containing a valid application deployment.
 176
 177 \until return
 178 \until }
 179
 180 \dontinclude msg/async-waitall/async-waitall.c
 181
 182 \paragraph MSG_ext_async_fct_Waitall Waitall function
 183
 184 The use of MSG_comm_waitall() allows a process to send all the tasks and then wait for the completion of all in one call.
 185
 186 \skipline static
 187 \until return
 188 \until }
 189
 190 \paragraph MSG_ext_async_fct_Waitany Waitany function
 191
 192 The MSG_comm_waitany() function returns the place of the first message send or receive from a xbt_dynar.
 193
 194 \skipline static
 195 \until return
 196 \until }
 197
 198 */
 199
 200