doc/user_guide/doxygen/use.doc

   1 /*! \page use Using SimGrid
   2
   3 SimGrid comes with many examples provided in the examples/ directory. Those examples are described in section \ref MSG_examples . Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below.
   4
   5 \htmlonly
   6 You should also check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a generic tutorial about using SimGrid.
   7 \endhtmlonly
   8
   9
  10 \section using_msg Using MSG
  11 \htmlonly
  12 You should also check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
  13 \endhtmlonly
  14
  15
  16
  17 Here are some examples on how to use MSG, the most used API.
  18
  19 tr
  20 MSG comes with an extensive set of examples. It is sometimes difficult
  21 to find the one you need. This list aims at helping you finding the
  22 example from which you can learn what you want to.
  23
  24 \subsection MSG_ex_basics Basic examples and features
  25
  26 \subsubsection MSG_ex_asynchronous_communications Asynchronous communications
  27
  28
  29 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
  30 an external description of the deployment.
  31
  32  - \ref MSG_ext_icomms_code
  33    - \ref MSG_ext_icomms_preliminary
  34    - \ref MSG_ext_icomms_Sender
  35    - \ref MSG_ext_icomms_Receiver
  36    - \ref MSG_ext_icomms_core
  37    - \ref MSG_ext_icomms_Main
  38  - \ref MSG_ext_icomms_fct_Waitall
  39  - \ref MSG_ext_icomms_fct_Waitany
  40
  41 <hr>
  42
  43 \dontinclude msg/icomms/peer.c
  44
  45 \paragraph MSG_ext_icomms_code Code of the application
  46
  47 \paragraph MSG_ext_icomms_preliminary Preliminary declarations
  48 \skip include
  49 \until Sender function
  50
  51 \paragraph MSG_ext_icomms_Sender Sender function
  52
  53 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
  54 we have to make "MSG_comm_test()" to know   if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
  55 It also available to "make MSG_comm_wait()" which make both of them.
  56
  57   C style arguments (argc/argv) are interpreted as:
  58    - the number of tasks to distribute
  59    - the computation size of each task
  60    - the size of the files associated to each task
  61    - a list of host that will accept those tasks.
  62    - the time to sleep at the beginning of the function
  63    - This time defined the process sleep time
  64                         if time = 0 use of MSG_comm_wait()
  65                         if time > 0 use of MSG_comm_test()
  66
  67
  68 \until Receiver function
  69
  70 \paragraph MSG_ext_icomms_Receiver Receiver function
  71
  72 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
  73 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
  74
  75   C style arguments (argc/argv) are interpreted as:
  76    - the id to use for received the communication.
  77    - the time to sleep at the beginning of the function
  78    - This time defined the process sleep time
  79                         if time = 0 use of MSG_comm_wait()
  80                         if time > 0 use of MSG_comm_test()
  81
  82 \until Test function
  83
  84 \paragraph MSG_ext_icomms_core Simulation core
  85
  86   This function is the core of the simulation and is divided only into 3 parts
  87   thanks to MSG_create_environment() and MSG_launch_application().
  88      -# Simulation settings : MSG_create_environment() creates a realistic
  89         environment
  90      -# Application deployment : create the processes on the right locations with
  91         MSG_launch_application()
  92      -# The simulation is run with #MSG_main()
  93
  94   Its arguments are:
  95         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
  96         - <i>application_file</i>: the name of a file containing a valid surfxml application description
  97
  98 \until Main function
  99
 100 \paragraph MSG_ext_icomms_Main Main function
 101
 102 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 103
 104 \until end_of_main
 105
 106 \dontinclude msg/icomms/peer2.c
 107
 108 \paragraph MSG_ext_icomms_fct_Waitall Waitall function for sender
 109
 110 The use of this function permit to send all messages and wait for the completion of all in one time.
 111
 112 \skipline Sender function
 113 \until end_of_sender
 114
 115 \paragraph MSG_ext_icomms_fct_Waitany Waitany function
 116
 117 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
 118
 119 \paragraph MSG_ext_icomms_fct_Waitany_sender From a sender
 120 We can use this function to wait all sent messages.
 121 \dontinclude msg/icomms/peer3.c
 122 \skipline Sender function
 123 \until end_of_sender
 124
 125 \paragraph MSG_ext_icomms_fct_Waitany_receiver From a receiver
 126 We can also wait for the arrival of all messages.
 127 \dontinclude msg/icomms/peer3.c
 128 \skipline Receiver function
 129 \until end_of_receiver
 130
 131 \subsubsection MSG_ex_master_slave Basic Master/Slaves
 132
 133 Simulation of a master-slave application using a realistic platform
 134 and an external description of the deployment.
 135
 136 \paragraph MSG_ex_ms_TOC Table of contents:
 137
 138    - \ref MSG_ext_ms_preliminary
 139    - \ref MSG_ext_ms_master
 140    - \ref MSG_ext_ms_slave
 141    - \ref MSG_ext_ms_forwarder
 142    - \ref MSG_ext_ms_core
 143    - \ref MSG_ext_ms_main
 144    - \ref MSG_ext_ms_helping
 145    - \ref MSG_ext_ms_application
 146    - \ref MSG_ext_ms_platform
 147
 148 <hr>
 149
 150 \dontinclude msg/masterslave/masterslave_forwarder.c
 151
 152
 153 \paragraph MSG_ext_ms_preliminary Preliminary declarations
 154
 155 \skip include
 156 \until printf
 157 \until }
 158
 159 \paragraph MSG_ext_ms_master Master code
 160
 161 This function has to be assigned to a msg_process_t that will behave as
 162 the master. It should not be called directly but either given as a
 163 parameter to #MSG_process_create() or registered as a public function
 164 through #MSG_function_register() and then automatically assigned to a
 165 process through #MSG_launch_application().
 166
 167 C style arguments (argc/argv) are interpreted as:
 168    - the number of tasks to distribute
 169    - the computation size of each task
 170    - the size of the files associated to each task
 171    - a list of host that will accept those tasks.
 172
 173 Tasks are dumbly sent in a round-robin style.
 174
 175 \until end_of_master
 176
 177 \paragraph MSG_ext_ms_slave Slave code
 178
 179 This function has to be assigned to a #msg_process_t that has to behave
 180 as a slave. Just like the master fuction (described in \ref
 181 MSG_ext_ms_master), it should not be called directly.
 182
 183 This function keeps waiting for tasks and executes them as it receives them.
 184
 185 \until end_of_slave
 186
 187 \paragraph MSG_ext_ms_forwarder Forwarder code
 188
 189 This function has to be assigned to a #msg_process_t that has to behave
 190 as a forwarder. Just like the master function (described in \ref
 191 MSG_ext_ms_master), it should not be called directly.
 192
 193 C style arguments (argc/argv) are interpreted as a list of host that
 194 will accept those tasks.
 195
 196 This function keeps waiting for tasks and dispathes them to its slaves.
 197
 198 \until end_of_forwarder
 199
 200 \paragraph MSG_ext_ms_core Simulation core
 201
 202 This function is the core of the simulation and is divided only into 3 parts
 203 thanks to MSG_create_environment() and MSG_launch_application().
 204    -# Simulation settings : MSG_create_environment() creates a realistic
 205       environment
 206    -# Application deployment : create the processes on the right locations with
 207       MSG_launch_application()
 208    -# The simulation is run with #MSG_main()
 209
 210 Its arguments are:
 211         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
 212         - <i>application_file</i>: the name of a file containing a valid surfxml application description
 213
 214 \until end_of_test_all
 215
 216 \paragraph MSG_ext_ms_main Main() function
 217
 218 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 219
 220 \until end_of_main
 221
 222 \subsubsection MSG_ext_ms_helping Helping files
 223
 224 \paragraph MSG_ext_ms_application Example of application file
 225
 226 \include msg/masterslave/deployment_masterslave.xml
 227
 228 \paragraph MSG_ext_ms_platform Example of platform file
 229
 230 \include msg/small_platform.xml
 231
 232 \section using_smpi Using SMPI
 233 You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
 234
 235 \section using_MC Using Model Checking
 236 You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
 237
 238 \section using_trace Using Trace
 239 Check out the \ref tracing section.
 240
 241 You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
 242
 243 \section using_simdag Using SimDag
 244 You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
 245
 246 \section using_simix Using SIMIX
 247 You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
 248
 249 */
 250
 251