Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
97dc7bcb39da33c25c914d2295aedf25667fbb39
[simgrid.git] / doc / FAQ.doc
1 /*! \page faq Frequently Asked Questions
2
3 \htmlinclude .FAQ.doc.toc
4
5 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
6
7 You are at the right  place... Having a look to these
8 <a href="http://www.loria.fr/~quinson/articles/simgrid-tutorial.pdf">the tutorial slides</a> 
9 (or to these <a href="http://graal.ens-lyon.fr/~alegrand/articles/slides_g5k_simul.pdf">old slides</a>,
10 or to these
11 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">"obsolete" slides</a>)
12 may give you some insights on what SimGrid can help you to do and what
13 are its limitations. Then you definitely should read the \ref
14 MSG_examples. The \ref GRAS_tut can also help you.
15
16 If you are stuck at any point and if this FAQ cannot help you, please drop us a
17 mail to the user mailing list: <simgrid-user@lists.gforge.inria.fr>.
18
19 \subsection faq_interfaces What is the difference between MSG, SimDag, and GRAS? Do they serve the same purpose?
20
21 It depend on how you define "purpose", I guess ;)
22
23 They all allow you to build a prototype of application which you can run
24 within the simulator afterward. They all share the same simulation kernel,
25 which is the core of the SimGrid project. They differ by the way you express
26 your application.
27
28 With SimDag, you express your code as a collection of interdependent
29 parallel tasks. So, in this model, applications can be seen as a DAG of
30 tasks. This is the interface of choice for people wanting to port old
31 code designed for SimGrid v1 or v2 to the framework current version.
32
33 With both GRAS and MSG, your application is seen as a set of communicating
34 processes, exchanging data by the way of messages and performing computation
35 on their own.
36
37 The difference between both is that MSG is somehow easier to use, but GRAS
38 is not limited to the simulator. Once you're done writing your GRAS code,
39 you can run your code both in the simulator or on a real platform. For this,
40 there is two implementations of the GRAS interface, one for simulation, one
41 for real execution. So, you just have to relink your code to chose one of
42 both world. 
43
44 \subsection faq_generic First steps with SimGrid
45
46 If you decide to go for the MSG interface, please read carefully the
47 \ref MSG_examples. You'll find in \ref MSG_ex_master_slave a very
48 simple consisting of a master (that owns a bunch of tasks and
49 distributes them) , some slaves (that process tasks whenever they
50 receive one) and some forwarder agents (that simply pass the tasks
51 they receive to some slaves).
52
53 If you decide to go for the GRAS interface, you should definitively
54 read the \ref GRAS_tut. The first section constitutes an introduction
55 to the tool and presents the model we use. The second section
56 constitutes a complete step-by-step tutorial building a distributed
57 application from the beginning and exemplifying most of the GRAS
58 features in the process. The last section groups some HOWTOS
59 highlighting a given feature of the framework in a more concise way.
60
61 If you decide to go for another interface, I'm afraid your only sources
62 of information will be the source code and the mailing lists...
63
64 \subsection faq_visualization Visualizing and analyzing the results
65
66 It is sometime convenient to "see" how the agents are behaving. If you
67 like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
68 as a filter to your MSG outputs. It works directly with INFO. Beware,
69 INFO() prints on stderr. Do not forget to redirect if you want to
70 filter (e.g. with bash): 
71 \verbatim 
72 ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
73 \endverbatim
74
75 We also have a more graphical output. Have a look at section \ref faq_tracing.
76
77 \subsection faq_C Argh! Do I really have to code in C?
78
79 Up until now, there is no binding for other languages. If you use C++,
80 you should be able to use the SimGrid library as a standard C library
81 and everything should work fine (simply <i>link</i> against this
82 library; recompiling SimGrid with a C++ compiler won't work and it
83 wouldn't help if you could).
84
85 In fact, we are currently working on Java bindings of MSG to allow
86 all the undergrad students of the world to use this tool. This is a
87 little more tricky than I would have expected, but the work is moving
88 fast forward [2006/05/13]. More languages are evaluated, but for now,
89 we do not feel a real demand for any other language. Please speak up!
90
91 \section faq_installation Installing the SimGrid library
92
93 Many people have been asking me questions on how to use SimGrid. Quite
94 often, the questions were not really about SimGrid but on the
95 installation process. This section is intended to help people that are
96 not familiar with compiling C files under UNIX. If you follow these
97 instructions and still have some troubles, drop an e-mail to
98 <simgrid-user@lists.gforge.inria.fr>.
99
100 \subsection faq_compiling Compiling SimGrid from a stable archive
101
102 First of all, you need to download the latest version of SimGrid from 
103 <a href="http://gforge.inria.fr/frs/?group_id=12">here</a>.
104 Suppose you have uncompressed SimGrid in some temporary location of
105 your home directory (say <tt>/home/joe/tmp/simgrid-3.0.1 </tt>). The
106 simplest way to use SimGrid is to install it in your home
107 directory. Change your directory to
108 <tt>/home/joe/tmp/simgrid-3.0.1</tt> and type
109
110 \verbatim
111 ./configure --prefix=$HOME
112 make
113 make install
114 \endverbatim
115
116 If at some point, something fails, check the section \ref faq_trouble_compil .
117 If it does not help, you can report this problem to the
118 list but, please, avoid sending a laconic mail like "There is a problem. Is it
119 okay?". Send the config.log file which is automatically generated by
120 configure. Try to capture both the standard output and the error output of the
121 <tt>make</tt> command with <tt>script</tt>. There is no way for us to help you
122 without the relevant bits of information.
123
124 Now, the following directory should have been created : 
125
126       \li <tt>/home/joe/doc/simgrid/html/</tt>
127       \li <tt>/home/joe/lib/</tt>
128       \li <tt>/home/joe/include/</tt>
129
130 SimGrid is not a binary, it is a library. Both a static and a dynamic
131 version are available. Here is what you can find if you try a <tt>ls
132 /home/joe/lib</tt>:
133
134 \verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
135 \endverbatim
136
137 Thus, there is two ways to link your program with SimGrid:
138       \li Either you use the static version, e.g 
139 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
140 \endverbatim
141           In this case, all the SimGrid functions are directly
142           included in <tt>MainProgram</tt> (hence a bigger binary).
143       \li Either you use the dynamic version (the preferred method)
144 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
145 \endverbatim
146           In this case, the SimGrid functions are not included in
147           <tt>MainProgram</tt> and you need to set your environment
148           variable in such a way that <tt>libsimgrid.so</tt> will be
149           found at runtime. This can be done by adding the following
150           line in your .bashrc (if you use bash and if you have
151           installed the SimGrid libraries in your home directory):
152 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
153 \endverbatim
154
155 \subsection faq_compiling_java Java bindings don't get compiled
156
157 The configure script detects automatically whether you have the
158 softwares needed to use the Java bindings or not. At the end of the
159 configure, you can see the configuration picked by the script, which
160 should look similar to 
161 \verbatim Configuration of package simgrid' (version 3.3.4-svn) on
162 little64 (=4):
163
164          Compiler:       gcc (version: )
165          
166          CFlags:          -O3 -finline-functions -funroll-loops -fno-strict-aliasing -Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror -g3
167          CPPFlags:   
168          LDFlags:        
169                                    
170          Context backend: ucontext
171          Compile Java: no
172                                                          
173          Maintainer mode: no
174          Supernovae mode: yes
175 \endverbatim       
176
177 In this example, Java backends won't be compiled. 
178
179 On Debian-like systems (which includes ubuntu), you need the following
180 packages: sun-java6-jdk libgcj10-dev. If you cannot find the
181 libgcj10-dev, try another version, like libgcj9-dev (on Ubuntu before
182 9.10) or libgcj11-dev (not released yet, but certainly one day).
183 Please note that you need to activate the contrib and non-free
184 repositories in Debian, and the universe ones in Ubuntu. Java comes at
185 this price...
186
187 \subsection faq_compiling_snapshoot SimGrid development snapshots
188
189 We have very high standards on software quality, and we are reluctant releasing
190 a stable release as long as there is still some known bug in the code base. In
191 addition, we added quite an extensive test base, making sure that we correctly
192 test the most important parts of the tool. 
193
194 As an unfortunate conclusion, there may be some time between the stable
195 releases. If you want to benefit from the most recent features we introduced,
196 but don't want to take the risk of an untested version from the SVN, then
197 development snapshots are done for you. 
198
199 These are pre-releases of SimGrid that still fail some tests about features
200 that almost nobody use, or on platforms not being in our core target (which is
201 Linux, Mac, other Unixes and Windows, from the most important to the less
202 one). That means that using this development releases should be safe for most
203 users. 
204
205 These archives can be found on 
206 <a href="http://www.loria.fr/~quinson/simgrid.html">this web page</a>. Once you 
207 got the lastest archive, you can compile it just like any archive (see above).
208
209 \subsection faq_compiling_svn Compiling SimGrid from the SVN
210
211 The project development takes place in the SVN, where all changes are
212 committed when they happen. Then every once in a while, we make sure that the
213 code quality meets our standard and release an archive from the code in the
214 SVN. We afterward go back to the development in the SVN. So, if you need a
215 recently added feature and can afford some little problem with the stability
216 of the lastest features, you may want to use the SVN version instead of a
217 released one.
218
219 For that, you first need to get the "simgrid" module from
220 <a href="http://gforge.inria.fr/scm/?group_id=12">here</a>. 
221
222 You won't find any <tt>configure</tt> and a few other things
223 (<tt>Makefile.in</tt>'s, documentation, ...) will be missing as well. The
224 reason for that is that all these files have to be regenerated using the
225 latest versions of <tt>autoconf</tt>, <tt>libtool</tt>, <tt>automake</tt>
226 (>1.9) and <tt>doxygen</tt> (>1.4). To generate the <tt>configure</tt> and
227 the <tt>Makefile.in</tt>'s, you just have to launch the <tt>bootstrap</tt>
228 command that resides in the top of the source tree. Then just follow the
229 instructions of Section \ref faq_compiling.
230
231 We insist on the fact that you really need the latest versions of
232 autoconf, automake and libtool. Doing this step on exotic architectures/systems
233 (i.e. anything different from a recent linux distribution) may be
234 ... uncertain. If you need to compile the SVN version on a machine where all these
235 dependencies are not met, the easiest is to do <tt>make dist</tt> in the SVN
236 directory of another machine where all dependencies are met. It will create an
237 archive you may deploy on other sites just as a regular stable release.
238
239 In summary, the following commands will checkout the SVN, regenerate the
240 configure script and friends, configure SimGrid and build it.
241
242 \verbatim svn checkout svn://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk simgrid
243 cd simgrid
244 ./bootstrap
245 ./configure --enable-maintainer-mode --prefix=<where to install SimGrid>
246 make \endverbatim
247
248 Then, if you want to install SimGrid on the current box, just do:
249 \verbatim make install \endverbatim
250
251 If you want to build an snapshot of the SVN to deploy it on another box (for
252 example because the other machine don't have the autotools), do:
253 \verbatim make dist \endverbatim
254
255 Moreover, you should never call the autotools manually since you must run
256 them in a specific order with specific arguments. Most of the times, the
257 makefiles will automatically call the tools for you. When it's not possible
258 (such as the first time you checkout the SVN), use the ./bootstrap command
259 to call them explicitly.
260
261
262 \subsection faq_setting_MSG Setting up your own MSG code
263
264 Do not build your simulator by modifying the SimGrid examples.  Go
265 outside the SimGrid source tree and create your own working directory
266 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
267
268 Suppose your simulation has the following structure (remember it is
269 just an example to illustrate a possible way to compile everything;
270 feel free to organize it as you want).
271
272       \li <tt>sched.h</tt>: a description of the core of the
273           scheduler (i.e. which functions are can be used by the
274           agents). For example we could find the following functions
275           (master, forwarder, slave).
276
277       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
278           implementing the core of the scheduler. Most of these
279           functions use the MSG functions defined in section \ref
280           msg_gos_functions.
281
282       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
283           the MSG initialization (MSG_global_init()), the platform
284           creation (e.g. with MSG_create_environment()), the
285           deployment phase (e.g. with MSG_function_register() and
286           MSG_launch_application()) and the call to
287           MSG_main()).
288
289 To compile such a program, we suggest to use the following
290 Makefile. It is a generic Makefile that we have used many times with
291 our students when we teach the C language.
292
293 \verbatim
294 all: masterslave 
295 masterslave: masterslave.o sched.o
296
297 INSTALL_PATH = $$HOME
298 CC = gcc
299 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
300                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
301                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
302                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
303                                 -Wpointer-arith -Wwrite-strings -finline-functions
304 REASONABLY_CAREFUL_DUDE =       -Wall
305 NO_PRAYER_FOR_THE_WICKED =      -w -O2 
306 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
307 CFLAGS = -g $(WARNINGS)
308
309 INCLUDES = -I$(INSTALL_PATH)/include
310 DEFS = -L$(INSTALL_PATH)/lib/
311 LDADD = -lm -lsimgrid 
312 LIBS = 
313
314 %: %.o
315         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ 
316
317 %.o: %.c
318         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
319
320 clean:
321         rm -f $(BIN_FILES) *.o *~
322 .SUFFIXES:
323 .PHONY : clean
324
325 \endverbatim
326
327 The first two lines indicates what should be build when typing make
328 (<tt>masterslave</tt>) and of which files it is to be made of
329 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
330 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
331 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
332 the static version, remove the <tt>-lsimgrid</tt> and add a
333 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
334 after the <tt>LIBS = </tt>.
335
336 More generally, if you have never written a Makefile by yourself, type
337 in a terminal : <tt>info make</tt> and read the introduction. The
338 previous example should be enough for a first try but you may want to
339 perform some more complex compilations...
340
341 \subsection faq_setting_GRAS Setting up your own GRAS code
342
343 If you use the GRAS interface instead of the MSG one, then previous section
344 is not the better source of information. Instead, you should check the GRAS
345 tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
346
347 \section faq_cmake CMAKE
348
349 \subsection faq_intro Some generalitty
350
351 \subsubsection faq_intro1 What is Cmake?
352
353 CMake is a family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. For more information see official web site <a href="http://www.cmake.org/">here</a>.
354
355 \subsubsection faq_intro2 Why cmake?
356
357 CMake permits to developers to compil projects on different plateform. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports. 
358
359 \subsubsection faq_intro3 What cmake need?
360
361 CMake needs some prerequists like :
362   \li make
363   \li c, c++ and java compiler regards to developers
364   \li ccmake for graphical used of CMake
365   \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
366
367 For windows only : 
368   \li Visual C++ 2010 Express <a href="http://www.microsoft.com/express/Downloads/#2010-Visual-CPP">(download page)</a>
369   \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
370   \li Set CC, CXX, INCLUDE, LIB and RC to environment variables.
371 \verbatim
372 SET --> CC      TO --> C:\MicrosoftVisualStudio10\VC\bin\cl
373     --> CXX        --> C:\MicrosoftVisualStudio10\VC\bin\cl
374     --> INCLUDE    --> C:\MicrosoftVisualStudio10\VC\include;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Include
375     --> LIB        --> C:\MicrosoftVisualStudio10\VC\lib;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Lib
376     --> RC         --> C:\Program Files\Microsoft SDKs\Windows\v7.OA\bin\RC
377 \endverbatim
378   \li Add to environment variable "Path" the path where to find nmake executable and some needed files.
379 \verbatim
380 ......
381 ;C\MicrosoftVisualStudio10\VC\bin
382 ;C\MicrosoftVisualStudio10\Common7\IDE
383 ;C:\Program Files\Microsoft SDKs\Windows\v7.OA\bin
384 ;C:\Program Files\Microsoft SDKs\Windows\v7.OA\Lib
385 ;C:\Program Files\Microsoft SDKs\Windows\v7.OA\bInclude
386 \endverbatim  
387 \subsection faq_cmakeoption Cmake options
388
389 \subsubsection faq_cmakeoption1 Liste of options
390
391 \verbatim
392 "cmake -D[name]=[value] ... ./"
393  
394 [name]          enable_gtnets                   [value] ON/OFF or TRUE/FALSE or 1/0
395                 enable_java                             ON/OFF or TRUE/FALSE or 1/0
396                 enable_lua                              ON/OFF or TRUE/FALSE or 1/0
397                 enable_ruby                             ON/OFF or TRUE/FALSE or 1/0
398                 enable_compile_optimizations            ON/OFF or TRUE/FALSE or 1/0
399                 enable_compile_warnings                 ON/OFF or TRUE/FALSE or 1/0
400                 enable_smpi                             ON/OFF or TRUE/FALSE or 1/0
401                 enable_maintainer_mode                  ON/OFF or TRUE/FALSE or 1/0
402                 enable_supernovae                       ON/OFF or TRUE/FALSE or 1/0
403                 enable_tracing                          ON/OFF or TRUE/FALSE or 1/0
404                 enable_coverage                         ON/OFF or TRUE/FALSE or 1/0
405                 enable_memcheck                         ON/OFF or TRUE/FALSE or 1/0 
406                 enable_model-checking                   ON/OFF or TRUE/FALSE or 1/0
407
408                 gtnets_path                             <path_to_gtnets_directory>
409                 prefix                                  <path_to_install_directory>
410                 BIBTEX2HTML                             <path_to_bibtex2html>
411                 with_context                            auto/ucontext/pthread/window     
412 \endverbatim
413                                                                                                                                                           
414 \subsubsection faq_cmakeoption2 Options explaination
415
416   \li enable_gtnets : set to true implie that user wants to use gtnets.
417
418   \li enable_java : set to true implie that user wants to add java langage into simgrid compilation.
419
420   \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
421
422   \li enable_ruby : set to true implie that user wants to add ruby langage into simgrid compilation.
423
424   \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
425
426   \li enable_compile_warnings : add flags "-Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror"
427
428   \li enable_smpi : Set to true if you want to use smpi lib. Actually on simgrid v3.4.1 Mac doesn't support lib smpi.
429
430   \li enable_maintainer_mode : set to true it remakes some files. 
431 \verbatim
432 include/surf/simgrid_dtd.h
433 include/xbt/graphxml.h
434
435 src/cunit_unit.c
436 src/ex_unit.c
437 src/dynar_unit.c
438 src/dict_unit.c
439 src/set_unit.c
440 src/swag_unit.c
441 src/xbt_str_unit.c
442 src/xbt_strbuff_unit.c
443 src/xbt_sha_unit.c
444 src/config_unit.c
445 src/xbt_synchro_unit.c
446 src/simgrid_units_main.c
447
448 src/simdag/dax_dtd.c
449 src/simdag/dax_dtd.h
450 src/simdag/dax_dtd.l
451
452 src/surf/simgrid_dtd.c
453 src/surf/simgrid_dtd.l
454
455 src/xbt/graphxml.c
456 src/xbt/graphxml.l
457
458 src/gras/DataDesc/ddt_parse.yy.c
459 \endverbatim
460   \li enable_supernovae : set to true make one file for each lib and compile with those generated files.
461 \verbatim
462 /src/supernovae_sg.c
463 /src/supernovae_gras.c                  
464 /src/supernovae_smpi.c
465 \endverbatim
466
467   \li enable_tracing : To enable the generation of simulation traces for visualization
468
469   \li enable_coverage : When set to true this option enable code coverage by setting -fprofile-arcs -ftest-coverage flags.
470
471   \li enable_memcheck : When set to true this option enable tests for memcheck.
472
473   \li enable_model-checking : Enable the model checking when set to true.
474
475   \li gtnets_path : Path to gtnets install directory (ex /usr)
476
477   \li prefix : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
478
479   \li BIBTEX2HTML : Path where is installed bibtex2html.
480
481   \li with context : specify which context the user wants to use.
482
483 \subsubsection faq_cmakeoption3 Initialisation
484
485 Those options are initialized the first time you launch "cmake ." whithout specified option.
486
487 \verbatim
488 enable_gtnets                   on
489 enable_lua                      on
490 enable_ruby                     on
491 enable_java                     off
492 enable_compile_optimizations    off
493 enable_compile_warnings         off
494 enable_smpi                     on
495 enable_maintainer_mode          off
496 enable_supernovae               off
497 enable_tracing                  off
498 enable_coverage                 off
499 enable_memcheck                 off
500 enable_model-checking           off
501
502 gtnets_path                     null
503 prefix                          null
504 BIBTEX2HTML                     null
505 with_context                    auto
506 \endverbatim
507
508 \subsubsection faq_cmakeoption4 Option's cache and how to reset?
509
510 When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want 
511 reset values you just delete this file located to the project directory.
512
513 \subsection faq_cmakecompilation Cmake compilation
514
515 \subsubsection faq_cmakecompilation1 With command line.
516
517 \verbatim
518 cmake -D[name]=[value] ... ./
519 make
520 \endverbatim
521
522 \subsubsection faq_cmakecompilation2 With ccmake tool.
523
524 \verbatim
525 "ccmake ./"
526 \endverbatim
527 Then follow instructions.
528
529 \subsubsection faq_cmakecompilation2bis Build out of source.
530
531 As cmake generate many files used for compilation, we recommand to make a build directory.
532 For examples you can make :
533
534 \verbatim
535 "navarrop@caraja:~/Developments$ cd simgrid/"
536 "navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
537 "navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
538 "navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
539 "navarrop@caraja:~/Developments/simgrid/build_directory$ make"
540 \endverbatim
541
542 Or complety out of sources :
543
544 \verbatim
545 "navarrop@caraja:~/Developments$ mkdir build_dir"
546 "navarrop@caraja:~/Developments$ cd build_dir/"
547 "navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
548 "navarrop@caraja:~/Developments/build_dir$ make"
549 \endverbatim
550
551 Those two kind of compilation permit to delete files created by compilation easier.
552
553 \subsubsection faq_cmakecompilation3 Resume of command line
554
555  \li CMake
556 \verbatim
557 cmake <path>            configure the project
558 make                    build all targets
559 make VERBOSE=1          build all targets and print build command lines
560 make check              test all targets and summarize
561 make dist               make the distrib
562 make distcheck          check the dist (make + make dist + make check) 
563 make install            install the project (doc/ lib/ include/)
564 make uninstall          uninstall the project (doc/ lib/ include/)
565 make clean              clean all targets
566 make java-clean         clean files created by java option
567 make doc-clean          clean files created for making doc
568 make supernovae-clean   clean supernovae files
569 make maintainer-clean   clean maintainer files
570 make all-clean          execute the 5 upper clean command
571 make html               Create simgrid documentation
572 \endverbatim
573
574 When the project have been succesfully compiling and build you can make tests.
575
576  \li CTest
577 \verbatim
578 ctest                   launch only tests
579 ctest -D Continuous
580 ctest -D Continuous(Start|Update|Configure|Build)
581 ctest -D Continuous(Test|Coverage|MemCheck|Submit)
582 ctest -D Experimental
583 ctest -D Experimental(Start|Update|Configure|Build)
584 ctest -D Experimental(Test|Coverage|MemCheck|Submit)
585 ctest -D Nightly                                
586 ctest -D Nightly(Start|Update|Configure|Build)
587 ctest -D Nightly(Test|Coverage|MemCheck|Submit)
588 ctest -D NightlyMemoryCheck
589 \endverbatim
590
591 If you want to test before make a commit you can simply make "ctest -D Experimental" and then you can visualize results submitted into Cdash. <a href="http://cdash.inria.fr/CDash/index.php?project=Simgrid">(Go to Cdash site)</a>.
592
593 \subsubsection faq_cmakecompilation4 Examples for different mode.
594
595 \li Mode maintainer
596
597 cmake -Denable_maintainer_mode=on ./
598 \verbatim 
599 -- lookign for config.h
600 with_context auto change to ucontext
601 GIT_DATE        : 2010-05-04~09-59-15
602 GIT_VERSION     : 53ec816
603 GIT_SVN_VERSION : 7669
604
605 Configuration of package `simgrid' (revision 7669) on arch (=4):
606              BUILDNAME :        UCONTEXT
607              SITE      :        Linux_2.6.31-21-generic_x86_64
608              Release   :        simgrid-3.4~rev7669
609
610          Compiler: c++ :        /usr/bin/c++
611                 version:        c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
612          Compiler: c   :        /usr/bin/gcc
613                 version:        gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
614
615                CFlags  :        -I/usr/lib/ruby/1.8/x86_64-linux -I/usr/include/lua5.1 -g3
616                CPPFlags:        
617                LDFlags :        -L/usr/lib/
618
619         Context backend:        ucontext
620         Compile Gtnets :        0
621         Gtnets path    :        
622         Compile Java   :        0
623         Compile Lua    :        1
624         Compile Ruby   :        1
625
626         Compile Smpi   :        ON
627         Maintainer mode:        ON
628         Supernovae mode:        OFF
629         Tracing mode   :        OFF
630
631         Simgrid dependencies:   -lm -lruby1.8 -module -ldl -llua5.1 -lrt
632         Gras dependencies   :   -lm -lpthread -lrt
633         Smpi dependencies   :   
634
635         INSTALL_PREFIX:         /usr/local
636
637 -- Configuring done
638 -- Generating done
639 -- Build files have been written to: /home/navarrop/Developments/simgrid
640 \endverbatim
641
642 \li Mode supernovae
643
644 cmake -Dsupernovae=on ./
645 \verbatim 
646 -- lookign for config.h
647 with_context auto change to ucontext
648 GIT_DATE        : 2010-05-04~09-59-15
649 GIT_VERSION     : 53ec816
650 GIT_SVN_VERSION : 7669
651
652 Configuration of package `simgrid' (revision 7669) on arch (=4):
653              BUILDNAME :        SUPERNOVAE
654              SITE      :        Linux_2.6.31-21-generic_x86_64
655              Release   :        simgrid-3.4~rev7669
656
657          Compiler: c++ :        /usr/bin/c++
658                 version:        c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
659          Compiler: c   :        /usr/bin/gcc
660                 version:        gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
661
662                CFlags  :        -O3 -finline-functions -funroll-loops -fno-strict-aliasing -Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror -I/usr/lib/ruby/1.8/x86_64-linux -I/usr/include/lua5.1 -g3
663                CPPFlags:        
664                LDFlags :        -L/usr/lib/
665
666         Context backend:        ucontext
667         Compile Gtnets :        0
668         Gtnets path    :        
669         Compile Java   :        0
670         Compile Lua    :        1
671         Compile Ruby   :        1
672
673         Compile Smpi   :        ON
674         Maintainer mode:        OFF
675         Supernovae mode:        OFF
676         Tracing mode   :        OFF
677
678         Simgrid dependencies:   -lm -lruby1.8 -module -ldl -llua5.1 -lrt
679         Gras dependencies   :   -lm -lpthread -lrt
680         Smpi dependencies   :   
681
682         INSTALL_PREFIX:         /usr/local
683
684 -- Configuring done
685 -- Generating done
686 -- Build files have been written to: /home/navarrop/Developments/simgrid
687
688 \endverbatim
689
690 \li Mode GTnetS
691
692 cmake -Dgtnets_path=/home/navarrop/Bureau/usr/ ./
693 \verbatim 
694 -- lookign for config.h
695 with_context auto change to ucontext
696 GIT_DATE        : 2010-05-04~09-59-15
697 GIT_VERSION     : 53ec816
698 GIT_SVN_VERSION : 7669
699
700 Configuration of package `simgrid' (revision 7669) on arch (=4):
701              BUILDNAME :        GTNETS
702              SITE      :        Linux_2.6.31-21-generic_x86_64
703              Release   :        simgrid-3.4~rev7669
704
705          Compiler: c++ :        /usr/bin/c++
706                 version:        c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
707          Compiler: c   :        /usr/bin/gcc
708                 version:        gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
709
710                CFlags  :        -O3 -finline-functions -funroll-loops -fno-strict-aliasing -Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror -I/usr/lib/ruby/1.8/x86_64-linux -L/usr/lib -I/usr/include/gtnets -I/usr/include/lua5.1 -g3
711                CPPFlags:        -L/usr/lib -I/usr/include/gtnets 
712                LDFlags :        -L/usr/lib/
713
714         Context backend:        ucontext
715         Compile Gtnets :        1
716         Gtnets path    :        /usr
717         Compile Java   :        0
718         Compile Lua    :        1
719         Compile Ruby   :        1
720
721         Compile Smpi   :        ON
722         Maintainer mode:        OFF
723         Supernovae mode:        OFF
724         Tracing mode   :        OFF
725
726         Simgrid dependencies:   -lm -lruby1.8 -module -ldl -llua5.1 -lgtnets -lrt
727         Gras dependencies   :   -lm -lpthread -lrt
728         Smpi dependencies   :   
729
730         INSTALL_PREFIX:         /usr/local
731
732 -- Configuring done
733 -- Generating done
734 -- Build files have been written to: /home/navarrop/Developments/simgrid
735
736 \endverbatim
737
738 \subsection faq_cmakeinstall How to install with cmake?
739
740 \subsubsection faq_cmakeinstall1 From svn. 
741
742 \verbatim
743 cmake -Denable_maintainer_mode=on -Dprefix=/home/navarrop/Bureau/install_simgrid ./
744 make 
745 make install
746 \endverbatim
747
748 \subsubsection faq_cmakeinstall2 From a distrib
749
750 \verbatim
751 cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
752 make
753 make install
754 \endverbatim
755
756 \subsection faq_cmakehowto How to modified sources files for developers
757
758 \subsubsection faq_cmakehowto1 Add an executable or examples.
759
760 If you want make an executable you have to create a CMakeList.txt to the src directory. 
761 You must specified where to create the executable, source list, dependencies and the name of the binary.
762
763 \verbatim
764 cmake_minimum_required(VERSION 2.6)
765
766 set(EXECUTABLE_OUTPUT_PATH "./")                        
767 set(LIBRARY_OUTPUT_PATH "${PROJECT_DIRECTORY}/lib")
768
769 add_executable(get_sender get_sender.c)                                 #add_executable(<name_of_target> <src list>)
770
771 ### Add definitions for compile
772 target_link_libraries(get_sender simgrid m pthread -fprofile-arcs)      #target_link_libraries(<name_of_targe> <dependencies>)
773 \endverbatim
774
775 Then you have to modified <project/directory>/buildtools/Cmake/CMakeMakeExeLib.txt and add 
776 this line :
777 \verbatim
778 add_subdirectory(${PROJECT_DIRECTORY}/<path_where_is_CMakeList.txt>)
779 \endverbatim
780
781 \subsubsection faq_cmakehowto2 Delete/add sources to lib.
782
783 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/CMakeDefinePackages.txt
784
785 \verbatim
786 set(JMSG_JAVA_SRC
787         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgException.java
788         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/JniException.java
789         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/NativeException.java
790         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
791         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
792         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Msg.java
793         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Process.java
794         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Host.java
795         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Task.java
796         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
797         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
798         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Sem.java
799 )
800 \endverbatim
801
802 \subsubsection faq_cmakehowto3 Add test
803
804 If you want modified, add or delete tests you have to edit <project/directory>/buildtools/Cmake/CMakeTest.txt 
805 with this function : ADD_TEST(<name> <bin> <ARGS>)
806
807 \verbatim
808 add_test(test-simdag-1 ${PROJECT_DIRECTORY}/testsuite/simdag/sd_test --cfg=path:${PROJECT_DIRECTORY}/testsuite/simdag small_platform_variable.xml)
809 \endverbatim
810
811 \subsection faq_cmakeExplain Explaination of sources files for cmake
812
813 \li CMakeLists.txt
814
815 Those files are the "main parts". One located at the project directory call all the cmake sources files. The others
816 are little projects called by the first for make examples.
817
818 \li CMakeCompleteInFiles.txt
819
820 Complete all .in files and define Variables for h files
821
822 \li CMakeDocs.txt
823
824 This file make the html documentation.
825
826 \li CMakeMakeExeLib.txt
827
828 Here are callled all "CMakeLists.txt" for make executables and libraries.
829
830 \li CMakePrintArgs.txt
831
832 This file is called at the end of the build for summarize environment variables.
833
834 \li CMakeDefinePackages.txt
835
836 Here is defined sources packages for compiling libs.
837
838 \li CMakeFlags.txt
839
840 Defined flags which are used for compiling sources.
841
842 \li CMakeSupernovae.txt
843
844 Here are made files for the supernovae mode.
845
846 \li CMakeDistrib.txt
847
848 Here is defined packages for install simgrid and make a distribution.
849
850 \li CMakeMaintainerMode.txt
851
852 Part where are generated source files for maintainer mode.
853
854 \li CMakeOption.txt
855
856 Here are defined options and initialized values.
857
858 \li CMakeTest.txt
859
860 All tests are listed.
861
862 \li CTestConfig.cmake
863
864 Properties which link tests with dashboard.
865
866 \subsection faq_cmakeList List of files added for cmake
867
868 Here is a list of files involved into cmake build (relative to project directory path) :
869 \verbatim
870
871 Cmake sources:
872         ./doc/CMakeLists.txt
873         ./buildtools/Cmake/AddTests.cmake
874         ./buildtools/Cmake/CompleteInFiles.cmake
875         ./buildtools/Cmake/CTestConfig.cmake
876         ./buildtools/Cmake/DefinePackages.cmake
877         ./buildtools/Cmake/Distrib.cmake
878         ./buildtools/Cmake/Flags.cmake
879         ./buildtools/Cmake/GenerateDocs.cmake
880         ./buildtools/Cmake/MaintainerMode.cmake
881         ./buildtools/Cmake/MakeExeLib.cmake
882         ./buildtools/Cmake/MakeJava.cmake
883         ./buildtools/Cmake/Option.cmake
884         ./buildtools/Cmake/PrintArgs.cmake
885         ./buildtools/Cmake/Supernovae.cmake
886         
887 CMakeLists for each binaries or examples:
888         ./CMakeLists.txt
889         ./src/CMakeLists.txt
890         ./teshsuite/gras/empty_main/CMakeLists.txt
891         ./teshsuite/gras/small_sleep/CMakeLists.txt
892         ./teshsuite/gras/datadesc/CMakeLists.txt
893         ./teshsuite/gras/msg_handle/CMakeLists.txt
894         ./teshsuite/simdag/CMakeLists.txt
895         ./teshsuite/simdag/partask/CMakeLists.txt
896         ./teshsuite/simdag/platforms/CMakeLists.txt
897         ./teshsuite/simdag/network/CMakeLists.txt
898         ./teshsuite/simdag/network/mxn/CMakeLists.txt
899         ./teshsuite/simdag/network/p2p/CMakeLists.txt
900         ./teshsuite/xbt/CMakeLists.txt
901         ./teshsuite/msg/CMakeLists.txt
902         ./tools/gras/CMakeLists.txt
903         ./tools/tesh/CMakeLists.txt
904         ./testsuite/simdag/CMakeLists.txt
905         ./testsuite/xbt/CMakeLists.txt
906         ./testsuite/surf/CMakeLists.txt
907         ./examples/gras/properties/CMakeLists.txt
908         ./examples/gras/ping/CMakeLists.txt
909         ./examples/gras/pmm/CMakeLists.txt
910         ./examples/gras/mmrpc/CMakeLists.txt
911         ./examples/gras/synchro/CMakeLists.txt
912         ./examples/gras/timer/CMakeLists.txt
913         ./examples/gras/mutual_exclusion/simple_token/CMakeLists.txt
914         ./examples/gras/spawn/CMakeLists.txt
915         ./examples/gras/chrono/CMakeLists.txt
916         ./examples/gras/rpc/CMakeLists.txt
917         ./examples/gras/all2all/CMakeLists.txt
918         ./examples/simdag/properties/CMakeLists.txt
919         ./examples/simdag/CMakeLists.txt
920         ./examples/simdag/metaxml/CMakeLists.txt
921         ./examples/simdag/dax/CMakeLists.txt
922         ./examples/smpi/CMakeLists.txt
923         ./examples/amok/bandwidth/CMakeLists.txt
924         ./examples/amok/saturate/CMakeLists.txt
925         ./examples/msg/priority/CMakeLists.txt
926         ./examples/msg/properties/CMakeLists.txt
927         ./examples/msg/migration/CMakeLists.txt
928         ./examples/msg/gtnets/CMakeLists.txt
929         ./examples/msg/parallel_task/CMakeLists.txt
930         ./examples/msg/trace/CMakeLists.txt
931         ./examples/msg/suspend/CMakeLists.txt
932         ./examples/msg/masterslave/CMakeLists.txt
933         ./examples/msg/actions/CMakeLists.txt
934         ./examples/msg/sendrecv/CMakeLists.txt
935 \endverbatim
936
937 \section faq_howto Feature related questions
938
939 \subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
940
941 Here is the deal. The whole SimGrid project (MSG, SURF, GRAS, ...) is
942 meant to be kept as simple and generic as possible. We cannot add
943 functions for everybody's needs when these functions can easily be
944 built from the ones already in the API. Most of the time, it is
945 possible and when it was not possible we always have upgraded the API
946 accordingly. When somebody asks us a question like "How to do that?
947 Is there a function in the API to simply do this?", we're always glad
948 to answer and help. However if we don't need this code for our own
949 need, there is no chance we're going to write it... it's your job! :)
950 The counterpart to our answers is that once you come up with a neat
951 implementation of this feature (task duplication, RPC, thread
952 synchronization, ...), you should send it to us and we will be glad to
953 add it to the distribution. Thus, other people will take advantage of
954 it (and we don't have to answer this question again and again ;).
955
956 You'll find in this section a few "Missing In Action" features. Many
957 people have asked about it and we have given hints on how to simply do
958 it with MSG. Feel free to contribute...
959
960 \subsection faq_MIA_MSG MSG features
961
962 \subsubsection faq_MIA_examples I want some more complex MSG examples!
963
964 Many people have come to ask me a more complex example and each time,
965 they have realized afterward that the basics were in the previous three
966 examples. 
967
968 Of course they have often been needing more complex functions like
969 MSG_process_suspend(), MSG_process_resume() and
970 MSG_process_isSuspended() (to perform synchronization), or
971 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
972 receptions), or even MSG_process_create() (to design asynchronous
973 communications or computations). But the examples are sufficient to
974 start.
975
976 We know. We should add some more examples, but not really some more
977 complex ones... We should add some examples that illustrate some other
978 functionalists (like how to simply encode asynchronous
979 communications, RPC, process migrations, thread synchronization, ...)
980 and we will do it when we will have a little bit more time. We have
981 tried to document the examples so that they are understandable. Tell
982 us if something is not clear and once again feel free to participate!
983 :)
984
985 \subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication
986
987 There is no task duplication in MSG. When you create a task, you can
988 process it or send it somewhere else. As soon as a process has sent
989 this task, he doesn't have this task anymore. It's gone. The receiver
990 process has got the task. However, you could decide upon receiving to
991 create a "copy" of a task but you have to handle by yourself the
992 semantic associated to this "duplication".
993
994 As we already told, we prefer keeping the API as simple as
995 possible. This kind of feature is rather easy to implement by users
996 and the semantic you associate really depends on people. Having a
997 *generic* task duplication mechanism is not that trivial (in
998 particular because of the data field). That is why I would recommand
999 that you write it by yourself even if I can give you advice on how to
1000 do it.
1001
1002 You have the following functions to get informations about a task:
1003 MSG_task_get_name(), MSG_task_get_compute_duration(),
1004 MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
1005 and MSG_task_get_data().
1006
1007 You could use a dictionary (#xbt_dict_t) of dynars (#xbt_dynar_t). If
1008 you still don't see how to do it, please come back to us...
1009
1010 \subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
1011
1012 Up until now, there is no asynchronous communications in MSG. However,
1013 you can create as many process as you want so you should be able to do
1014 whatever you want... I've written a queue module to help implementing
1015 some asynchronous communications at low cost (creating thousands of
1016 process only to handle communications may be problematic in term of
1017 performance at some point). I'll add it in the distribution asap.
1018
1019 \subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
1020
1021 You obviously cannot use pthread_mutexes of pthread_conds. The best
1022 thing would be to propose similar structures. Unfortunately, we
1023 haven't found time to do it yet. However you can try to play with
1024 MSG_process_suspend() and MSG_process_resume(). You can even do some
1025 synchronization with fake communications (using MSG_task_get(),
1026 MSG_task_put() and MSG_task_Iprobe()).
1027
1028 \subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
1029
1030 There is no such thing because its semantic wouldn't be really
1031 clear. Of course, it is something about the amount of host throughput,
1032 but there is as many definition of "host load" as people asking for
1033 this function. First, you have to remember that resource availability
1034 may vary over time, which make any load notion harder to define.
1035
1036 It may be instantaneous value or an average one. Moreover it may be only the
1037 power of the computer, or may take the background load into account, or may
1038 even take the currently running tasks into account. In some SURF models,
1039 communications have an influence on computational power. Should it be taken
1040 into account too?
1041
1042 First of all, it's near to impossible to predict the load beforehands in the
1043 simulator since it depends on too much parameters (background load
1044 variation, bandwidth sharing algorithmic complexity) some of them even being
1045 not known beforehands (other task starting at the same time). So, getting
1046 this information is really hard (just like in real life). It's not just that
1047 we want MSG to be as painful as real life. But as it is in some way
1048 realistic, we face some of the same problems as we would face in real life.
1049
1050 How would you do it for real? The most common option is to use something
1051 like NWS that performs active probes. The best solution is probably to do
1052 the same within MSG, as in next code snippet. It is very close from what you
1053 would have to do out of the simulator, and thus gives you information that
1054 you could also get in real settings to not hinder the realism of your
1055 simulation. 
1056
1057 \verbatim
1058 double get_host_load() {
1059    m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
1060    double date = MSG_get_clock();
1061
1062    MSG_task_execute(task);
1063    date = MSG_get_clock() - date;
1064    MSG_task_destroy(task);
1065    return (0.001/date);
1066 }
1067 \endverbatim
1068
1069 Of course, it may not match your personal definition of "host load". In this
1070 case, please detail what you mean on the mailing list, and we will extend
1071 this FAQ section to fit your taste if possible.
1072
1073 \subsubsection faq_MIA_communication_time How can I get the *real* communication time?  
1074
1075 Communications are synchronous and thus if you simply get the time
1076 before and after a communication, you'll only get the transmission
1077 time and the time spent to really communicate (it will also take into
1078 account the time spent waiting for the other party to be
1079 ready). However, getting the *real* communication time is not really
1080 hard either. The following solution is a good starting point.
1081
1082 \verbatim
1083 int sender()
1084 {
1085   m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size, 
1086                                   calloc(1,sizeof(double)));
1087   *((double*) task->data) = MSG_get_clock();
1088   MSG_task_put(task, slaves[i % slaves_count], PORT_22);
1089   INFO0("Send completed");
1090   return 0;
1091 }
1092 int receiver()
1093 {
1094   m_task_t task = NULL;
1095   double time1,time2;
1096
1097   time1 = MSG_get_clock();
1098   a = MSG_task_get(&(task), PORT_22);
1099   time2 = MSG_get_clock();
1100   if(time1<*((double *)task->data))
1101      time1 = *((double *) task->data);
1102   INFO1("Communication time :  \"%f\" ", time2-time1);
1103   free(task->data);
1104   MSG_task_destroy(task);
1105   return 0;
1106 }
1107 \endverbatim
1108
1109 \subsection faq_MIA_SimDag SimDag related questions
1110
1111 \subsubsection faq_SG_comm Implementing communication delays between tasks.
1112
1113 A classic question of SimDag newcomers is about how to express a
1114 communication delay between tasks. The thing is that in SimDag, both
1115 computation and communication are seen as tasks.  So, if you want to
1116 model a data dependency between two DAG tasks t1 and t2, you have to
1117 create 3 SD_tasks: t1, t2 and c and add dependencies in the following
1118 way:
1119
1120 \verbatim
1121 SD_task_dependency_add(NULL, NULL, t1, c);
1122 SD_task_dependency_add(NULL, NULL, c, t2);
1123 \endverbatim
1124
1125 This way task t2 cannot start before the termination of communication c
1126 which in turn cannot start before t1 ends.
1127
1128 When creating task c, you have to associate an amount of data (in bytes)
1129 corresponding to what has to be sent by t1 to t2.
1130
1131 Finally to schedule the communication task c, you have to build a list
1132 comprising the workstations on which t1 and t2 are scheduled (w1 and w2
1133 for example) and build a communication matrix that should look like
1134 [0;amount ; 0; 0].
1135
1136 \subsubsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs.
1137
1138 Distributed is somehow "contagious". If you start making distributed
1139 decisions, there is no way to handle DAGs directly anymore (unless I
1140 am missing something). You have to encode your DAGs in term of
1141 communicating process to make the whole scheduling process
1142 distributed. Here is an example of how you could do that. Assume T1
1143 has to be done before T2.
1144
1145 \verbatim
1146  int your_agent(int argc, char *argv[] {
1147    ...
1148    T1 = MSG_task_create(...);
1149    T2 = MSG_task_create(...);
1150    ...
1151    while(1) {
1152      ...
1153      if(cond) MSG_task_execute(T1);
1154      ...
1155      if((MSG_task_get_remaining_computation(T1)=0.0) && (you_re_in_a_good_mood))
1156         MSG_task_execute(T2)
1157      else {
1158         /* do something else */
1159      }
1160    }
1161  }
1162 \endverbatim
1163  
1164 If you decide that the distributed part is not that much important and that
1165 DAG is really the level of abstraction you want to work with, then you should
1166 give a try to \ref SD_API.
1167
1168 \subsection faq_MIA_generic Generic features
1169
1170 \subsubsection faq_more_processes Increasing the amount of simulated processes
1171
1172 Here are a few tricks you can apply if you want to increase the amount
1173 of processes in your simulations.
1174
1175  - <b>A few thousands of simulated processes</b> (soft tricks)\n
1176    SimGrid can use either pthreads library or the UNIX98 contextes. On
1177    most systems, the number of pthreads is limited and then your
1178    simulation may be limited for a stupid reason. This is especially
1179    true with the current linux pthreads, and I cannot get more than
1180    2000 simulated processes with pthreads on my box. The UNIX98
1181    contexts allow me to raise the limit to 25,000 simulated processes
1182    on my laptop.\n\n
1183    The <tt>--with-context</tt> option of the <tt>./configure</tt>
1184    script allows you to choose between UNIX98 contextes
1185    (<tt>--with-context=ucontext</tt>) and the pthread version
1186    (<tt>--with-context=pthread</tt>). The default value is ucontext
1187    when the script detect a working UNIX98 context implementation. On
1188    Windows boxes, the provided value is discarded and an adapted
1189    version is picked up.\n\n
1190    We experienced some issues with contextes on some rare systems
1191    (solaris 8 and lower or old alpha linuxes comes to mind). The main
1192    problem is that the configure script detect the contextes as being
1193    functional when it's not true. If you happen to use such a system,
1194    switch manually to the pthread version, and provide us with a good
1195    patch for the configure script so that it is done automatically ;)
1196
1197  - <b>Hundred thousands of simulated processes</b> (hard-core tricks)\n 
1198    As explained above, SimGrid can use UNIX98 contextes to represent
1199    and handle the simulated processes. Thanks to this, the main
1200    limitation to the number of simulated processes becomes the
1201    available memory.\n\n
1202    Here are some tricks I had to use in order to run a token ring
1203    between 25,000 processes on my laptop (1Gb memory, 1.5Gb swap).\n
1204    - First of all, make sure your code runs for a few hundreds
1205      processes before trying to push the limit. Make sure it's
1206      valgrind-clean, ie that valgrind does not report neither memory
1207      error nor memory leaks. Indeed, numerous simulated processes
1208      result in *fat* simulation hindering debugging.
1209    - It was really boring to write 25,000 entries in the deployment
1210      file, so I wrote a little script
1211      <tt>examples/gras/mutual_exclusion/simple_token/make_deployment.pl</tt>, which you may
1212      want to adapt to your case. You could also think about hijacking
1213      the SURFXML parser (have look at \ref faq_flexml_bypassing).
1214    - The deployment file became quite big, so I had to do what is in
1215      the FAQ entry \ref faq_flexml_limit
1216    - Each UNIX98 context has its own stack entry. As debugging this is
1217      quite hairly, the default value is a bit overestimated so that
1218      user don't get into trouble about this. You want to tune this
1219      size to increse the number of processes. This is the
1220      <tt>STACK_SIZE</tt> define in 
1221      <tt>src/xbt/xbt_context_sysv.c</tt>, which is 128kb by default.
1222      Reduce this as much as you can, but be warned that if this value
1223      is too low, you'll get a segfault. The token ring example, which
1224      is quite simple, runs with 40kb stacks.     
1225    - You may tweak the logs to reduce the stack size further.  When
1226      logging something, we try to build the string to display in a
1227      char array on the stack. The size of this array is constant (and
1228      equal to XBT_LOG_BUFF_SIZE, defined in include/xbt/log/h). If the
1229      string is too large to fit this buffer, we move to a dynamically
1230      sized buffer. In which case, we have to traverse one time the log
1231      event arguments to compute the size we need for the buffer,
1232      malloc it, and traverse the argument list again to do the actual
1233      job.\n     
1234      The idea here is to move XBT_LOG_BUFF_SIZE to 1, forcing the logs
1235      to use a dynamic array each time. This allows us to lower further
1236      the stack size at the price of some performance loss...\n
1237      This allowed me to run the reduce the stack size to ... 4k. Ie,
1238      on my 1Gb laptop, I can run more than 250,000 processes!
1239
1240 \subsubsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid?
1241
1242 No, there is no native support for batch schedulers and none is
1243 planned because this is a very specific need (and doing it in a
1244 generic way is thus very hard). However some people have implemented
1245 their own batch schedulers. Vincent Garonne wrote one during his PhD
1246 and put his code in the contrib directory of our SVN so that other can
1247 keep working on it. You may find inspiring ideas in it.
1248
1249 \subsubsection faq_MIA_checkpointing I need a checkpointing thing
1250
1251 Actually, it depends on whether you want to checkpoint the simulation, or to
1252 simulate checkpoints. 
1253
1254 The first one could help if your simulation is a long standing process you
1255 want to keep running even on hardware issues. It could also help to
1256 <i>rewind</i> the simulation by jumping sometimes on an old checkpoint to
1257 cancel recent calculations.\n 
1258 Unfortunately, such thing will probably never exist in SG. One would have to
1259 duplicate all data structures because doing a rewind at the simulator level
1260 is very very hard (not talking about the malloc free operations that might
1261 have been done in between). Instead, you may be interested in the Libckpt
1262 library (http://www.cs.utk.edu/~plank/plank/www/libckpt.html). This is the
1263 checkpointing solution used in the condor project, for example. It makes it
1264 easy to create checkpoints (at the OS level, creating something like core
1265 files), and rerunning them on need.
1266
1267 If you want to simulate checkpoints instead, it means that you want the
1268 state of an executing task (in particular, the progress made towards
1269 completion) to be saved somewhere.  So if a host (and the task executing on
1270 it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted
1271 from the last checkpoint.\n
1272
1273 Actually, such a thing does not exists in SimGrid either, but it's just
1274 because we don't think it is fundamental and it may be done in the user code
1275 at relatively low cost. You could for example use a watcher that
1276 periodically get the remaining amount of things to do (using
1277 MSG_task_get_remaining_computation()), or fragment the task in smaller
1278 subtasks.
1279
1280 \subsection faq_platform Platform building and Dynamic resources
1281
1282 \subsubsection faq_platform_example Where can I find SimGrid platform files?
1283
1284 There is several little examples in the archive, in the examples/msg
1285 directory. From time to time, we are asked for other files, but we
1286 don't have much at hand right now. 
1287
1288 You should refer to the Platform Description Archive
1289 (http://pda.gforge.inria.fr) project to see the other platform file we
1290 have available, as well as the Simulacrum simulator, meant to generate
1291 SimGrid platforms using all classical generation algorithms.
1292
1293 \subsubsection faq_platform_alnem How can I automatically map an existing platform?
1294
1295 We are working on a project called ALNeM (Application-Level Network
1296 Mapper) which goal is to automatically discover the topology of an
1297 existing network. Its output will be a platform description file
1298 following the SimGrid syntax, so everybody will get the ability to map
1299 their own lab network (and contribute them to the catalog project).
1300 This tool is not ready yet, but it move quite fast forward. Just stay
1301 tuned.
1302
1303 \subsubsection faq_platform_synthetic Generating synthetic but realistic platforms
1304
1305 The third possibility to get a platform file (after manual or
1306 automatic mapping of real platforms) is to generate synthetic
1307 platforms. Getting a realistic result is not a trivial task, and
1308 moreover, nobody is really able to define what "realistic" means when
1309 speaking of topology files. You can find some more thoughts on this
1310 topic in these
1311 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
1312
1313 If you are looking for an actual tool, there we have a little tool to
1314 annotate Tiers-generated topologies. This perl-script is in
1315 <tt>tools/platform_generation/</tt> directory of the SVN. Dinda et Al.
1316 released a very comparable tool, and called it GridG.
1317
1318 \subsubsection faq_SURF_dynamic Expressing dynamic resource availability in platform files
1319
1320 A nice feature of SimGrid is that it enables you to seamlessly have
1321 resources whose availability change over time. When you build a
1322 platform, you generally declare hosts like that:
1323
1324 \verbatim
1325   <host id="host A" power="100.00"/>
1326 \endverbatim 
1327
1328 If you want the availability of "host A" to change over time, the only
1329 thing you have to do is change this definition like that:
1330
1331 \verbatim
1332   <host id="host A" power="100.00" availability_file="trace_A.txt" state_file="trace_A_failure.txt"/>
1333 \endverbatim
1334
1335 For hosts, availability files are expressed in fraction of available
1336 power. Let's have a look at what "trace_A.txt" may look like:
1337
1338 \verbatim
1339 PERIODICITY 1.0
1340 0.0 1.0
1341 11.0 0.5
1342 20.0 0.9
1343 \endverbatim
1344
1345 At time 0, our host will deliver 100 flop/s. At time 11.0, it will
1346 deliver only 50 flop/s until time 20.0 where it will will start
1347 delivering 90 flop/s. Last at time 21.0 (20.0 plus the periodicity
1348 1.0), we'll be back to the beginning and it will deliver 100 flop/s.
1349
1350 Now let's look at the state file:
1351 \verbatim
1352 PERIODICITY 10.0
1353 1.0 -1.0
1354 2.0 1.0
1355 \endverbatim
1356
1357 A negative value means "off" while a positive one means "on". At time
1358 1.0, the host is on. At time 1.0, it is turned off and at time 2.0, it
1359 is turned on again until time 12 (2.0 plus the periodicity 10.0). It
1360 will be turned on again at time 13.0 until time 23.0, and so on.
1361
1362 Now, let's look how the same kind of thing can be done for network
1363 links. A usual declaration looks like:
1364
1365 \verbatim
1366   <link id="LinkA" bandwidth="10.0" latency="0.2"/>
1367 \endverbatim
1368
1369 You have at your disposal the following options: bandwidth_file,
1370 latency_file and state_file. The only difference with hosts is that
1371 bandwidth_file and latency_file do not express fraction of available
1372 power but are expressed directly in bytes per seconds and seconds.
1373
1374 \subsubsection faq_platform_multipath How to express multipath routing in platform files?
1375
1376 It is unfortunately impossible to express the fact that there is more
1377 than one routing path between two given hosts. Let's consider the
1378 following platform file:
1379
1380 \verbatim
1381 <route src="A" dst="B">
1382    <link:ctn id="1"/>
1383 </route>
1384 <route src="B" dst="C">
1385   <link:ctn id="2"/>
1386 </route>
1387 <route src="A" dst="C">
1388   <link:ctn id="3"/>
1389 </route>
1390 \endverbatim
1391
1392 Although it is perfectly valid, it does not mean that data traveling
1393 from A to C can either go directly (using link 3) or through B (using
1394 links 1 and 2). It simply means that the routing on the graph is not
1395 trivial, and that data do not following the shortest path in number of
1396 hops on this graph. Another way to say it is that there is no implicit
1397 in these routing descriptions. The system will only use the routes you
1398 declare (such as &lt;route src="A" dst="C"&gt;&lt;link:ctn
1399 id="3"/&gt;&lt;/route&gt;), without trying to build new routes by aggregating
1400 the provided ones.
1401   
1402 You are also free to declare platform where the routing is not
1403 symmetric. For example, add the following to the previous file:
1404
1405 \verbatim
1406 <route src="C" dst="A">
1407   <link:ctn id="2"/>
1408   <link:ctn id="1"/>
1409 </route>
1410 \endverbatim
1411
1412 This makes sure that data from C to A go through B where data from A
1413 to C go directly. Don't worry about realism of such settings since
1414 we've seen ways more weird situation in real settings (in fact, that's
1415 the realism of very regular platforms which is questionable, but
1416 that's another story).
1417
1418 \subsubsection faq_flexml_bypassing Bypassing the XML parser with your own C functions
1419
1420 So you want to bypass the XML files parser, uh? Maybe doing some parameter
1421 sweep experiments on your simulations or so? This is possible, and
1422 it's not even really difficult (well. Such a brutal idea could be
1423 harder to implement). Here is how it goes.
1424
1425 For this, you have to first remember that the XML parsing in SimGrid is done
1426 using a tool called FleXML. Given a DTD, this gives a flex-based parser. If
1427 you want to bypass the parser, you need to provide some code mimicking what
1428 it does and replacing it in its interactions with the SURF code. So, let's
1429 have a look at these interactions.
1430
1431 FleXML parser are close to classical SAX parsers. It means that a
1432 well-formed SimGrid platform XML file might result in the following
1433 "events":
1434
1435   - start "platform_description" with attribute version="2"
1436   - start "host" with attributes id="host1" power="1.0"
1437   - end "host"
1438   - start "host" with attributes id="host2" power="2.0"
1439   - end "host"
1440   - start "link" with ...
1441   - end "link"
1442   - start "route" with ...
1443   - start "link:ctn" with ...
1444   - end "link:ctn"
1445   - end "route"
1446   - end "platform_description"
1447
1448 The communication from the parser to the SURF code uses two means:
1449 Attributes get copied into some global variables, and a surf-provided
1450 function gets called by the parser for each event. For example, the event
1451   - start "host" with attributes id="host1" power="1.0"
1452
1453 let the parser do something roughly equivalent to:
1454 \verbatim
1455   strcpy(A_host_id,"host1");
1456   A_host_power = 1.0;
1457   STag_host();
1458 \endverbatim
1459
1460 In SURF, we attach callbacks to the different events by initializing the
1461 pointer functions to some the right surf functions. Since there can be
1462 more than one callback attached to the same event (if more than one
1463 model is in use, for example), they are stored in a dynar. Example in
1464 workstation_ptask_L07.c:
1465 \verbatim
1466   /* Adding callback functions */
1467   surf_parse_reset_parser();
1468   surfxml_add_callback(STag_surfxml_host_cb_list, &parse_cpu_init);
1469   surfxml_add_callback(STag_surfxml_prop_cb_list, &parse_properties);
1470   surfxml_add_callback(STag_surfxml_link_cb_list, &parse_link_init);
1471   surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints);
1472   surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem);
1473   surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route);
1474                 
1475   /* Parse the file */
1476   surf_parse_open(file);
1477   xbt_assert1((!surf_parse()), "Parse error in %s", file);
1478   surf_parse_close();
1479 \endverbatim
1480     
1481 So, to bypass the FleXML parser, you need to write your own version of the
1482 surf_parse function, which should do the following:
1483    - Fill the A_<tag>_<attribute> variables with the wanted values
1484    - Call the corresponding STag_<tag>_fun function to simulate tag start
1485    - Call the corresponding ETag_<tag>_fun function to simulate tag end
1486    - (do the same for the next set of values, and loop)
1487
1488 Then, tell SimGrid that you want to use your own "parser" instead of the stock one:
1489 \verbatim
1490   surf_parse = surf_parse_bypass_environment;
1491   MSG_create_environment(NULL);
1492   surf_parse = surf_parse_bypass_application;
1493   MSG_launch_application(NULL);
1494 \endverbatim
1495
1496 A set of macros are provided at the end of
1497 include/surf/surfxml_parse.h to ease the writing of the bypass
1498 functions. An example of this trick is distributed in the file
1499 examples/msg/masterslave/masterslave_bypass.c
1500
1501 \subsection faq_simgrid_configuration Changing SimGrid's behavior
1502
1503 A number of options can be given at runtime to change the default
1504 SimGrid behavior. In particular, you can change the default cpu and
1505 network models...
1506
1507 \subsubsection faq_simgrid_configuration_gtnets Using GTNetS
1508
1509 It is possible to use a packet-level network simulator
1510 instead of the default flow-based simulation. You may want to use such
1511 an approach if you have doubts about the validity of the default model
1512 or if you want to perform some validation experiments. At the moment,
1513 we support the GTNetS simulator (it is still rather experimental
1514 though, so leave us a message if you play with it). 
1515
1516
1517 <i>
1518 To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code 
1519 and build/install it from scratch
1520 </i>
1521
1522  - <b>Download and enter the recent downloaded GTNetS directory</b>
1523
1524  \verbatim
1525  svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
1526  cd GTNetS
1527  \endverbatim
1528
1529
1530  - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
1531
1532  \verbatim
1533  unzip gtnets-current.zip
1534  tar zxvf gtnets-current-patch.tgz 
1535  cd gtnets-current
1536  cat ../00*.patch | patch -p1
1537  \endverbatim
1538
1539   - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
1540
1541   \verbatim
1542   cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
1543   \endverbatim
1544
1545  - <b>Compile GTNetS</b>
1546
1547    Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS. 
1548
1549
1550  \verbatim
1551  ln -sf Makefile.linux Makefile
1552  make depend
1553  make debug
1554  \endverbatim
1555
1556
1557  - <b>NOTE</b> A lot of warnings are expected but the application should compile
1558  just fine. If the makefile insists in compiling some QT libraries
1559  please try a make clean before asking for help.
1560
1561
1562  - <b>To compile optimized version</b>
1563
1564  \verbatim
1565  make opt
1566  \endverbatim
1567
1568
1569  - <b>Installing GTNetS</b>
1570
1571  It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
1572
1573  \verbatim
1574  ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
1575  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
1576  mkdir /<userhome>/usr/include/gtnets
1577  cp -fr SRC/*.h /<userhome>/usr/include/gtnets
1578  \endverbatim
1579
1580
1581  - <b>Enable GTNetS support in SimGrid</b>
1582
1583    \verbatim
1584    ./configure --with-gtnets=/<userhome>/usr
1585    \endverbatim
1586
1587  - <b>Once you have followed all the instructions for compiling and
1588    installing successfully you can activate this feature at 
1589    runntime with the following options:</b>
1590
1591    \verbatim
1592    cd simgrid/example/msg/
1593    make
1594    make check
1595    \endverbatim
1596
1597
1598  - <b>Or try the GTNetS model dogbone example with</b>
1599
1600  \verbatim
1601  gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
1602  \endverbatim
1603
1604  
1605  A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a>  it is available 
1606
1607
1608  More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
1609
1610
1611  - <b>DISCLAIMER</b>
1612  The patches provided by us worked successfully with GTNetS found 
1613  <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>, 
1614  dated from 12th June 2008. Due to the discontinuing development of
1615  GTNetS it is impossible to precise a version number. We STRONGLY recommend you
1616  to download and install the GTNetS version found in SimGrid repository as explained above.
1617  
1618
1619
1620
1621 \subsubsection faq_simgrid_configuration_alternate_network Using alternative flow models
1622
1623 The default simgrid network model uses a max-min based approach as
1624 explained in the research report
1625 <a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A Network Model for Simulation of Grid Application</a>.
1626 Other models have been proposed and implemented since then (see for example 
1627 <a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
1628 and can be activated at runtime. For example:
1629 \verbatim
1630 ./mycode platform.xml deployment.xml --cfg=workstation/model:compound --cfg=network/model:LV08 -cfg=cpu/model:Cas01
1631 \endverbatim
1632
1633 Possible models for the network are currently "Constant", "CM02",
1634 "LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
1635 probably be added in the future and many of the previous ones are
1636 experimental and are likely to disappear without notice... To know the
1637 list of the currently  implemented models, you should use the
1638 --help-models command line option.
1639
1640 \verbatim
1641 ./masterslave_forwarder ../small_platform.xml deployment_masterslave.xml  --help-models
1642 Long description of the workstation models accepted by this simulator:
1643   CLM03: Default workstation model, using LV08 and CM02 as network and CPU
1644   compound: Workstation model allowing you to use other network and CPU models
1645   ptask_L07: Workstation model with better parallel task modeling
1646 Long description of the CPU models accepted by this simulator:
1647   Cas01_fullupdate: CPU classical model time=size/power
1648   Cas01: Variation of Cas01_fullupdate with partial invalidation optimization of lmm system. Should produce the same values, only faster
1649   CpuTI: Variation of Cas01 with also trace integration. Should produce the same values, only faster if you use availability traces
1650 Long description of the network models accepted by this simulator:
1651   Constant: Simplistic network model where all communication take a constant time (one second)
1652   CM02: Realistic network model with lmm_solve and no correction factors
1653   LV08: Realistic network model with lmm_solve and these correction factors: latency*=10.4, bandwidth*=.92, S=8775
1654   Reno: Model using lagrange_solve instead of lmm_solve (experts only)
1655   Reno2: Model using lagrange_solve instead of lmm_solve (experts only)
1656   Vegas: Model using lagrange_solve instead of lmm_solve (experts only)
1657 \endverbatim
1658
1659 \subsection faq_tracing Tracing Simulations for Visualization
1660
1661 The trace visualization is widely used to observe and understand the behavior
1662 of parallel applications and distributed algorithms. Usually, this is done in a
1663 two-step fashion: the user instruments the application and the traces are
1664 analyzed after the end of the execution. The visualization itself can highlights
1665 unexpected behaviors, bottlenecks and sometimes can be used to correct
1666 distributed algorithms. The SimGrid team is currently instrumenting the library
1667 in order to let users trace their simulations and analyze them. This part of the
1668 user manual explains how the tracing-related features can be enabled and used
1669 during the development of simulators using the SimGrid library.
1670
1671 \subsubsection faq_tracing_howitworks How it works
1672
1673 For now, the SimGrid library is instrumented so users can trace the <b>platform
1674 utilization</b> using the MSG interface. This means that the tracing will
1675 register how much power is used for each host and how much bandwidth is used for
1676 each link of the platform. The idea with this type of tracing is to observe the
1677 overall view of resources utilization in the first place, especially the
1678 identification of bottlenecks, load-balancing among hosts, and so on.
1679
1680 The idea of the instrumentation is to classify the MSG tasks by category,
1681 and trace
1682 the platform utilization (hosts and links) for each of the categories. For that,
1683 the tracing interface enables the declaration of categories and a function to
1684 mark a task with a previously declared category. <em>The tasks that are not
1685 classified according to a category are not traced</em>.
1686
1687 \subsubsection faq_tracing_enabling Enabling using CMake
1688
1689 With the sources of SimGrid, it is possible to enable the tracing 
1690 using the parameter <b>-Dtracing=on</b> when the cmake is executed.
1691 The section \ref faq_tracing_functions describes all the functions available
1692 when this Cmake options is activated. These functions will have no effect
1693 if SimGrid is configured without this option (they are wiped-out by the
1694 C-preprocessor).
1695
1696 \verbatim
1697 $ cmake -Dtracing=on .
1698 $ make
1699 \endverbatim
1700
1701 \subsubsection faq_tracing_functions Tracing Functions
1702
1703 \subsubsubsection Mandatory Functions
1704
1705 \li <b>\c TRACE_start (const char *filename)</b>: This is the first function to
1706 be called. It receives a single argument as parameter that contains the name of
1707 the file that will hold the trace in the end of the simulation. It returns 0 if
1708 everything was properly initialized, 1 otherwise. All trace functions called
1709 before TRACE_start do nothing.
1710
1711 \li <b>\c TRACE_category (const char *category)</b>: This function should be used
1712 to define a user category. The category can be used to differentiate the tasks
1713 that are created during the simulation (for example, tasks from server1,
1714 server2, or request tasks, computation tasks, communication tasks).
1715 All resource utilization (host power and link bandwidth) will be
1716 classified according to the task category. Tasks that do not belong to a
1717 category are not traced.
1718
1719 \li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
1720 This function should be called after the creation of a task, to define the
1721 category of that task. The first parameter \c task must contain a task that was
1722 created with the function \c MSG_task_create. The second parameter
1723 \c category must contain a category that was previously defined by the function
1724 \c TRACE_category.
1725
1726 \li <b>\c TRACE_end ()</b>: This is the last function to be called. It closes
1727 the trace file and stops the tracing of the simulation. All tracing will be
1728 completely disabled after the calling this function. Although we recommend
1729 the use of this function somewhere in the end of program, it can be used
1730 anywhere in the code. This function returns 0 if everything is ok, 1 otherwise.
1731
1732 \subsubsubsection Optional Functions
1733
1734 \li <b>\c TRACE_host_variable_declare (const char *variable)</b>:
1735 Declare a user variable that will be associated to hosts. A variable can
1736 be used to trace user variables such as the number of tasks in a server,
1737 the number of clients in an application, and so on.
1738
1739 \li <b>\c TRACE_host_variable_[set|add|sub] (const char *variable, double
1740 value)</b>:
1741 Set the value of a given user variable. It is important to remind that
1742 the value of this variable is always associated to the host. The host
1743 that will be used when these functions are called is the one returned by
1744 the function \c MSG_host_self().
1745
1746 \subsubsection faq_tracing_example Example of Instrumentation
1747
1748 A simplified example using the tracing mandatory functions.
1749
1750 \verbatim
1751 int main (int argc, char **argv)
1752 {
1753   TRACE_start ("traced_simulation.trace");
1754   TRACE_category ("request");
1755   TRACE_category ("computation");
1756   TRACE_category ("finalize");
1757   
1758   MSG_global_init (&argc, &argv);
1759
1760   //(... after deployment ...)
1761
1762   m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
1763   m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
1764   m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
1765   m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
1766   TRACE_msg_set_task_category (req1, "request");
1767   TRACE_msg_set_task_category (req2, "request");
1768   TRACE_msg_set_task_category (req3, "request");
1769   TRACE_msg_set_task_category (req4, "request");
1770
1771   m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
1772   TRACE_msg_set_task_category (comp, "computation");
1773
1774   m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
1775   TRACE_msg_set_task_category (finalize, "finalize");
1776
1777   //(...)
1778
1779   MSG_clean();
1780  
1781   TRACE_end();
1782   return 0;
1783 }
1784 \endverbatim
1785
1786 \subsubsection faq_tracing_analyzing Analyzing the SimGrid Traces
1787
1788 The SimGrid library, during an instrumented simulation, creates a trace file in
1789 the Paje file format that contains the platform utilization for the simulation
1790 that was executed. The visualization analysis of this file is performed with the
1791 visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
1792 special configurations tunned to SimGrid needs. This part of the documentation
1793 explains how to configure and use Triva to analyse a SimGrid trace file.
1794
1795 - <b>Installing Triva</b>: the tool is available in the INRIAGforge, 
1796 at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
1797 Use the following command to get the sources, and then check the file
1798 <i>INSTALL.simplified</i>. This file contains instructions to install
1799 the tool's dependencies in a Ubuntu/Debian Linux.
1800 \verbatim
1801 $ svn checkout svn://scm.gforge.inria.fr/svn/triva
1802 $ cd triva
1803 $ cat INSTALL.simplified
1804 \endverbatim
1805
1806 - <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
1807   installation (you can execute it passing <em>--help</em> to check its
1808 options). If the triva binary is not available after following the
1809 installation instructions, you may want to execute the following command to
1810 initialize the GNUstep environment variables (note that the location of the
1811 <i>GNUstep.sh</i> file may vary depending on your GNUstep installation - the
1812 command is known to work in Ubuntu and Debian Linux):
1813 \verbatim
1814 $ source /usr/share/GNUstep/Makefiles/GNUstep.sh
1815 \endverbatim
1816 You should be able to see this output after the installation of triva:
1817 \verbatim
1818 $ ./Triva.app/Triva --help
1819 Usage: Triva [OPTION...] TRACEFILE
1820 Trace Analysis through Visualization
1821
1822  You need to use one of the following options:
1823   -g, --graph                Graph Analysis
1824   -t, --treemap              Treemap Analysis
1825
1826  Other auxiliary options to check the trace file:
1827   -c, --check                Check the integrity of trace file
1828   -h, --hierarchy            Export the trace type hierarchy
1829   -l, --list                 List entity types
1830
1831   -?, --help                 Give this help list
1832       --usage                Give a short usage message
1833 \endverbatim
1834 Triva expects that the user choose one of the available options 
1835 (currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
1836 and the trace file from the simulation.
1837
1838 - <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
1839   the tool always takes into account the concept of the <em>time-slice</em>.
1840 This concept means that what is being visualized in the screen is always
1841 calculated considering a specific time frame, with its beggining and end
1842 timestamp. The time-slice is configured by the user and can be changed
1843 dynamically through the window called <em>Time Interval</em> that is opened
1844 whenever a trace file is being analyzed. The next figure depicts the time-slice
1845 configuration window.
1846 In the top of the window, in the space named <i>Trace Time</i>,
1847 the two fields show the beggining of the trace (which usually starts in 0) and
1848 the end (that depends on the time simulated by SimGrid). The middle of the
1849 window, in the square named <i>Time Slice Configuration</i>, contains the
1850 aspects related to the time-slice, including its <i>start</i> and its
1851 <i>size</i>. The gray rectangle in the bottom of this part indicates the 
1852 <i>current time-slice</i> that is considered for the drawings. If the checkbox 
1853 <i>Update Drawings on Sliders Change</i> is not selected, the button
1854 <i>Apply</i> must be clicked in order to inform triva that the
1855 new time-slice must be considered. The bottom part of the window, in the space
1856 indicated by the square <i>Time Slice Animation</i> can be used to advance
1857 the time-frame automatically. The user configures the amount of time that the
1858 time-frame will forward and how frequent this update will happen. Once this is
1859 configured, the user clicks the <i>Play</i> button in order to see the dynamic
1860 changes on the drawings.
1861 <center>
1862 \htmlonly
1863 <a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
1864 \endhtmlonly
1865 </center>
1866 <b>Remarks:</b> when the trace has too many hosts or links, the computation to
1867 take into account a new time-slice can be expensive. When this happens, the
1868 <i>Frequency</i> parameter, but also updates caused by change on configurations
1869 when the checkbox <i>Update Drawings on Sliders
1870 Change</i> is selected will not be followed.
1871
1872 - <b>Understanding Triva - graph</b>: this part of the documention explains how
1873   to analyze the traces using the graph view of Triva, when the user executes
1874 the tool passing <em>--graph</em> as parameter. Triva opens three windows when
1875 this parameter is used: the <i>Time Interval</i> window (previously described),
1876 the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
1877 window. The Graph Representation is the window where drawings take place.
1878 Initially, it is completely white waiting for a proper graph configuration input
1879 by the user. We start the description of this type of analysis by describing the
1880 <i>Graph Configuration</i> window (depicted below). By using a particular
1881 configuration, triva
1882 can be used to customize the graph drawing according to
1883 the SimGrid trace that was created with user-specific categories. Before delving
1884 into the details of this customization, let us first explain the major parts of
1885 the graph configuration window. The buttons located in the top-right corner can
1886 be used to delete, copy and create a new configuration. The checkbox in the
1887 top-middle part of the window indicates if the configuration typed in the
1888 textfield is syntactically correct (we are using the non-XML 
1889 <a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
1890 describe the configuration). The pop-up button located on the top-left corner 
1891 indicates the selected configuration (the user can have multiple graph
1892 configurations). The bottom-left text field contains the name of the current
1893 configuration (updates on this field must be followed by typing enter on the
1894 keyboard to take into account the name change). The bottom-right <em>Apply</em>
1895 button activates the current configuration, resulting on an update on the graph
1896 drawings.
1897 <center>
1898 \htmlonly
1899 <a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
1900 \endhtmlonly
1901 </center>
1902 <b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
1903 basic configuration that should be used during the analysis of a SimGrid trace
1904 file. The basic logic of the configuration is as follows:
1905 \verbatim
1906 {
1907   node = (HOST);
1908   edge = (LINK);
1909 \endverbatim
1910 The nodes of the graph will be created based on the <i>node</i> parameter, which
1911 in this case is the different <em>"HOST"</em>s of the platform 
1912 used to simulate. The <i>edge</i> parameter indicates that the edges of the
1913 graph will be created based on the <em>"LINK"</em>s of the platform. After the
1914 definition of these two parameters, the configuration must detail how
1915 <em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
1916 must have an entry for each of the types used. For <em>HOST</em>, as basic
1917 configuration, we have:
1918 \verbatim
1919   HOST = {
1920     size = power;
1921     scale = global;
1922   };
1923 \endverbatim
1924 The parameter <em>size</em> indicates which variable from the trace file will be
1925 used to define the size of the node HOST in the visualization. If the simulation
1926 was executed with availability traces, the size of the nodes will be changed
1927 according to these traces. The parameter <em>scale</em> indicates if the value
1928 of the variable is <em>global</em> or <em>local</em>. If it is global, the value
1929 will be relative to the power of all other hosts, if it is local, the value will
1930 be relative locally.
1931 For <em>LINK</em> we have:
1932 \verbatim
1933   LINK = {
1934     src = SrcHost;
1935     dst = DstHost;
1936     
1937     size = bandwidth;
1938     scale = global;
1939   };
1940 \endverbatim
1941 For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
1942 the configuration must contain two additional parameters: <em>src</em> and
1943 <em>dst</em> that are used to properly identify which nodes this edge is
1944 connecting. The values <em>SrcHost</em> and <em>DstHost</em> are always present
1945 in the SimGrid trace file and should not be changed in the configuration. The
1946 parameter <em>size</em> for the LINK, in this case, is configured as the
1947 variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
1948 here is exactly the same used for nodes. The last parameter is the GraphViz
1949 algorithm used to calculate the position of the nodes in the graph
1950 representation.
1951 \verbatim
1952   graphviz-algorithm = neato;
1953 }
1954 \endverbatim
1955 <b>Customizing the Graph Representation</b>: triva is capable to handle
1956 a customized graph representation based on the variables present in the trace
1957 file. In the case of SimGrid, every time a category is created for tasks, two
1958 variables in the trace file are defined: one to indicate node utilization (how
1959 much power was used by that task category), and another to indicate link
1960 utilization (how much bandwidth was used by that category). For instance, if the
1961 user declares a category named <i>request</i>, there will be variables named
1962 <b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
1963 <b>b</b> for bandwidth). It is important to notice that the variable
1964 <i>prequest</i> in this case is only available for HOST, and
1965 <i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
1966 two categories for tasks: request and compute. To create a customized graph
1967 representation with a proportional separation of host and link utilization, use
1968 as configuration for HOST and LINK this:
1969 \verbatim
1970   HOST = {
1971     size = power;
1972     scale = global;
1973   
1974     sep_host = {
1975       type = separation;
1976       size = power;
1977       values = (prequest, pcomputation);
1978     };
1979   };
1980
1981   LINK = {
1982     src = SrcHost;
1983     dst = DstHost;
1984     size = bandwidth;
1985     scale = global;
1986
1987     sep_link = {
1988       type = separation;
1989       size = bandwidth;
1990       values = (brequest, bcomputation);
1991     };
1992   };
1993 \endverbatim
1994 Where <i>sep_host</i> contains a composition of type <i>separation</i> where
1995 its max size is the <i>power</i> of the host and the variables <i>prequest</i>
1996 and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
1997 <i>sep_link</i> is also a separation where max is defined as the
1998 <i>bandwidth</i> of the link, and the variables <i>brequest</i> and
1999 <i>bcomputation</i> are drawn proportionally within a LINK.
2000 <i>This configuration enables the analysis of resource utilization by MSG tasks,
2001 and the identification of load-balancing issues, network bottlenecks, for
2002 instance.</i> \n
2003 <b>Other compositions</b>: besides <i>separation</i>, it is possible to use
2004 other types of compositions, such as gradients, and colors, like this:
2005 \verbatim
2006     gra_host = {
2007       type = gradient;
2008       scale = global;
2009       values = (numberOfTasks);
2010     };
2011     color_host = {
2012       type = color;
2013       values = (is_server);
2014     };
2015 \endverbatim
2016 Where <i>gra_host</i> creates a gradient within a node of the graph, using a
2017 global scale and using as value a variable called <i>numberOfTasks</i>, that
2018 could be declared by the user using the optional tracing functions of SimGrid.
2019 If scale is global, the max and min value for the gradient will be equal to the
2020 max and min numberOfTasks among all hosts, and if scale is local, the max and
2021 min value based on the value of numberOfTasks locally in each host.
2022 And <i>color_host</i> composition draws a square based on a positive value of
2023 the variable <i>is_server</i>, that could also be defined by the user using the
2024 SimGrid tracing functions. \n
2025 <b>The Graph Visualization</b>: The next figure shows a graph visualization of a
2026 given time-slice of the masterslave_forwarder example (present in the SimGrid
2027 sources). The red color indicates tasks from the <i>compute</i> category. This
2028 visualization was generated with the following configuration:
2029 \verbatim
2030 {
2031   node = (HOST);
2032   edge = (LINK);
2033
2034   HOST = {
2035     size = power;
2036     scale = global;
2037   
2038     sep_host = {
2039       type = separation;
2040       size = power;
2041       values = (pcompute, pfinalize);
2042     };
2043   };
2044   LINK = {
2045     src = SrcHost;
2046     dst = DstHost;
2047     size = bandwidth;
2048     scale = global;
2049
2050     sep_link = {
2051       type = separation;
2052       size = bandwidth;
2053       values = (bcompute, bfinalize);
2054     };
2055   };
2056   graphviz-algorithm = neato;
2057 }
2058 \endverbatim
2059 <center>
2060 \htmlonly
2061 <a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
2062 \endhtmlonly
2063 </center>
2064
2065 - <b>Understading Triva - colors</b>: An important issue when using Triva is how
2066   to define colors. To do that, we have to know which variables are defined in
2067 the trace file generated by the SimGrid library. The parameter <em>--list</em> 
2068 lists the variables for a given trace file:
2069 \verbatim
2070 $ Triva -l masterslave_forwarder.trace
2071 iFile
2072 c  platform
2073 c    HOST
2074 v     power
2075 v     is_slave
2076 v     is_master
2077 v     task_creation
2078 v     task_computation
2079 v     pcompute
2080 v     pfinalize
2081 c    LINK
2082 v     bandwidth
2083 v     latency
2084 v     bcompute
2085 v     bfinalize
2086 c  user_type
2087 \endverbatim
2088 We can see that HOST has seven variables (from power to pfinalize) and LINK has
2089 four (from bandwidth to bfinalize). To define a red color for the
2090 <i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
2091 <i>compute</i>), execute:
2092 \verbatim
2093 $ defaults write Triva 'pcompute Color' '1 0 0'
2094 $ defaults write Triva 'bcompute Color' '1 0 0'
2095 \endverbatim
2096 Where the three numbers in each line are the RGB color with values from 0 to 1.
2097
2098 \subsection faq_modelchecking Model-Checking
2099 \subsubsection faq_modelchecking_howto How to use it
2100 To enable the experimental SimGrid model-checking support the program should
2101 be executed with the command line argument 
2102 \verbatim
2103 --cfg=model-check:1 
2104 \endverbatim
2105 Properties are expressed as assertions using the function
2106 \verbatim
2107 void MC_assert(int prop);
2108 \endverbatim
2109
2110 \subsection faq_binding_lua Lua Binding
2111 Most of Simgrid modules require a  good level in C programming ,
2112  since simgrid is used to be as standard C library .
2113  Sometime ( for some reason or another ) developers prefer using some kind of « easy scripts »
2114  (something like … lua ? Ruby ? ...?)  or a language easier to code with ( Java ? ) for their works ,
2115  which avoid dealing with C errors , and sometime an important  gain of time (coding-time?) .
2116 Besides Java Binding , Lua  and Ruby bindings are available now( since version 3.4 of Simgrid )
2117 for MSG Module , and we are currenlty working on bindings for other modules .
2118
2119
2120 \subsubsection faq_binding_lua_about What is lua ?
2121 Lua (Moon for portuguese !) is a lightweight, reflective, imperative and functional programming language,
2122  designed as a scripting language with extensible semantics as a primary goal.(see official web site <a href="http://www.lua.org">here</a>)
2123 \subsubsection faq_binding_lua_why Why lua ?
2124 Lua is a fast,portable and powerful script language , quite simple to use for developpers .
2125 it combines procedural features with powerful data description facilities,
2126  by using a simple, yet powerful, mechanism of tables.
2127 Lua has a relatively simple C API compared to other scripting languages,
2128 and accordingly it provides a robust, easy to use it.
2129 \subsubsection faq_binding_lua_simgrid How to use lua in Simgrid ?
2130 Actually , the use of lua in Simgrid is quite simple , you have just to follow the same steps as coding with C in Simgird ,
2131  but this time , code with Lua ;) :
2132   - Coding functions coresponding to each process
2133   - loading the platforme/deployment XML file that describe the environment of simulation
2134   - and … Running the Simulation !!!
2135   
2136 \subsubsection faq_binding_lua_example_master_slave Master/Slave Example
2137  \li Master Code
2138 \verbatim
2139 function Master(...)
2140   nb_task = arg[1];
2141   comp_size = arg[2];
2142   comm_size = arg[3];
2143   slave_count = arg[4]
2144   -- Dispatch the tasks
2145   for i=1,nb_task do
2146     tk = simgrid.Task.new("Task "..i,comp_size,comm_size);
2147     alias = "slave "..(i%slave_count);
2148     simgrid.info("Master sending ’" .. simgrid.Task.name(tk) .."’ To ’" .. alias .."’");
2149     simgrid.Task.send(tk,alias);
2150     simgrid.info("Master done sending ’".. simgrid.Task.name(tk) .."’ To ’" .. alias .."’");
2151   end
2152   -- Sending Finalize Message To Others
2153   for i=0,slave_count-1 do
2154     alias = "slave "..i;
2155     simgrid.info("Master: sending finalize to "..alias);
2156     finalize = simgrid.Task.new("finalize",comp_size,comm_size);
2157     simgrid.Task.send(finalize,alias)
2158   end
2159 end
2160 \endverbatim
2161 we mainly  use   simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task , 
2162          then simgrid.Task.send(task,alias) to send it .
2163 we  use also simgrid.Task.name(task), to get the task's name . 
2164
2165 \li Slave Code
2166 \verbatim
2167 function Slave(...)
2168   local my_mailbox="slave "..arg[1]
2169   while true do
2170     local tk = simgrid.Task.recv(my_mailbox);
2171     if (simgrid.Task.name(tk) == "finalize") then
2172       simgrid.info("Slave ’" ..my_mailbox.."’ got finalize msg");
2173       break
2174     end
2175     simgrid.Task.execute(tk)
2176   end
2177   simgrid.info("Slave ’" ..my_mailbox.."’: I’m Done . See You !!");
2178 end
2179 \endverbatim
2180 Here , we could see how we use  simgrid.Task.recv(alias) to receive a task with a specific alias ,
2181 this function return directly the task recevied .
2182
2183 \li Set Environmenet and run application
2184 \verbatim
2185 require "simgrid"
2186 simgrid.platform("my_platform.xml")
2187 simgrid.application("my_deployment.xml")
2188 simgrid.run()
2189 simgrid.info("Simulation’s over.See you.")
2190 simgrid.clean()
2191 \endverbatim
2192
2193 \subsubsection faq_binding_lua_example_data Exchanging Data
2194 You can also exchange data between Process using lua .for that , you have to deal with  lua task as a table ,
2195 since lua is based itself on a mechanism of tables ,
2196 so  you can exchange any kind of data ( tables, matrix , strings … ) between process via tasks.
2197
2198 \li Sender process
2199 \verbatim 
2200   task = simgrid.Task.new("data_task",task_comp,task_comm);
2201   task['matrix'] = my_matrix;
2202   task['table'] = my_table;
2203   task['message'] = "Hello from (Lua || Simgrid ) !! "
2204   …
2205   simgrid.Task.send(task,alias)
2206 \endverbatim
2207         After creating task , we associate to it  various kind of data with a specific key , ( string in this case)
2208         to distinguish between data variables . Via this key the receiver could access easily to  datas .
2209
2210
2211 \li Receiver processe
2212 \verbatim
2213   task = simgrid.Task.recv(alias);
2214   sender_matrix = task['matrix'];
2215   sender_table = task['table'];
2216   sender_message = task['message']
2217   ...
2218 \endverbatim
2219         Note that in lua , both sender and receiver share the same lua task ! 
2220         So that the receiver could joint data directly on the received task without sending it back .
2221         You can find  a complet example ( matrix multiplication case ) in the file example/lua/mult_matrix.lua 
2222
2223
2224 \subsubsection faq_binding_lua_example_bypass Bypass XML
2225         maybe you wonder if there is a way to bypass the XML files ,
2226          and describe your platform directly from the code , with lua bindings it's Possible !! how ?
2227         We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
2228      ( this can be useful for large platforms , so a simple for loop will avoid you to deal with an annoying XML File ;) )
2229      
2230
2231 \li set Hosts
2232 \verbatim
2233   simgrid.Host.new("Tremblay",98095000);
2234   simgrid.Host.new("Jupiter",76296000);
2235   simgrid.Host.new("Fafard",76296000);
2236   simgrid.Host.new("Ginette",48492000);
2237   simgrid.Host.new("Bourassa",48492000);
2238 \endverbatim
2239   we use simgrid.Host.new(host_id,power) to instanciate our hosts.
2240
2241 \li set Links
2242 \verbatim
2243   for i=0,11 do
2244     simgrid.Link.new(i,252750+ i*768,0.000270544+i*0.087);    --  some crazy values ;)
2245   end
2246 \endverbatim
2247   we used simgrid.Link.new(link_id,bandwidth,latency) with a simple for loop to create all links we need  ( much easier than XML hein ? )
2248
2249 \li set Routes
2250 \verbatim
2251 -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
2252    simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
2253    simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
2254    simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
2255    simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
2256
2257    simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
2258    simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
2259    simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
2260    simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
2261    ...
2262 \endverbatim
2263   for each host you have to specify which route to choose to access to the rest of hosts connected in the grid .
2264   
2265 \li Save platform
2266 \verbatim
2267   simgrid.register_platform();
2268 \endverbatim
2269 Don't forget to register your platform , that SURF callbacks starts their work ;)
2270
2271 \li set application
2272 \verbatim
2273    simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
2274    simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
2275    simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
2276    simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
2277    simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
2278 \endverbatim
2279   you don't  need to use a deployment XML file , thanks to  simgrid.Host.setFunction(host_id,function,args_number,args_list) 
2280   you can associate functions for each host with arguments if needed .
2281
2282 \li
2283 \verbatim
2284    simgrid.register_application();
2285 \endverbatim
2286 Yes , Here too you have to resgiter your application before running the simulation .
2287
2288 the full example is distributed in the file examples/lua/master_slave_bypass.lua
2289
2290 \subsection faq_binding_ruby Ruby Binding
2291
2292 \subsubsection faq_binding_ruby_about What is Ruby ?
2293 Ruby is a dynamic, reflective, general purpose object-oriented programming language that combines syntax inspired by Perl with Smalltalk-like features.
2294 Ruby supports multiple programming paradigms, including functional, object oriented, imperative and reflective. It also has a dynamic type system and automatic memory management;
2295 it is therefore similar in varying respects to Python, Perl, Lisp, Dylan, Pike, and CLU.(see official web site <a href="http://ruby-lang.org">here</a>)
2296
2297 \subsubsection faq_binding_ruby_simgrid Use Ruby in Simgrid
2298 Since v3.4 , the use of ruby in simgrid is available for the MSG Module .
2299 you can find almost all MSG functionalities in Ruby code , that allows you to set up your environment , manage tasks between hosts and run the simulation.
2300
2301 \subsubsection faq_binding_ruby_example Master/Slave Ruby Application
2302 for each process method(master and slave in this example), you have to associate a ruby class , that should inherit from <i>MSG::Process</i> ruby class,
2303   with a 'main' function that describe the behaviour of the process during the simulation.
2304 \li required stuff
2305 \verbatim
2306 require 'simgrid'
2307 include MSG
2308 \endverbatim
2309
2310 \li Master code
2311 \verbatim
2312 #################################################
2313 # Class Master
2314 #################################################
2315 class Master < MSG::Process  
2316   # main : that function that will be executed when running simulation
2317
2318   def main(args) # args is an array containing arguments for function master
2319    size = args.size
2320    for i in 0..size-1
2321      MSG::info("args["+String(i)+"]="+args[i])
2322    end
2323   
2324    raise "Master needs 3 arguments" if size < 3 
2325    numberOfTask = Integer(args[0]) 
2326    taskComputeSize = Float(args[1])
2327    taskCommunicationSize = Float(args[2])
2328    slaveCount = Integer(args[3]) 
2329    
2330    # Creates and sends the tasks
2331     for i in 0..numberOfTask-1
2332      task = Task.new("Task_"+ i.to_s, taskComputeSize , taskCommunicationSize);
2333      mailbox = "slave " + (i%slaveCount).to_s
2334      MSG::info("Master Sending "+ task.name + " to " + mailbox + " with Comput Size " + 
2335            task.compSize.to_s)
2336      task.send(mailbox)
2337      MSG::info("Master Done Sending " + task.name + " to " + mailbox)
2338     end
2339   
2340    # Sending Finalize MSG::Tasks
2341    MSG::info("Master: All tasks have been dispatched. Let's tell everybody the computation is over.")
2342    for i in 0..slaveCount-1
2343      mailbox = "slave " + i.to_s
2344      finalize_task = Task.new("finalize",0,0)
2345      finalize_task.send(mailbox)
2346    end
2347    MSG::info("Master : Everything's Done")
2348   end    
2349 end
2350 \endverbatim
2351 the class MSG::Task contains methods that allows the management of the native MSG tasks.
2352 in master ruby code we used : 
2353   - <i>MSG::Task.new(task_name,compute_size,communication_size)</i> : to instanciate a new task.
2354   - <i>MSG::Task.send(mailbox)</i> : to send the task via a mailbox alias.
2355   - <i>MSG::Task.name</i> : to get the task's name.
2356
2357 \li Slave code
2358 \verbatim
2359 #################################################
2360 # Class Slave
2361 #################################################
2362 class Slave < MSG::Process
2363
2364   def main(args)
2365     mailbox = "slave " + args[0]
2366     for i in 0..args.size-1
2367       MSG::debug("args["+String(i)+"]="+args[i])
2368     end
2369
2370     while true
2371        task = Task.receive(mailbox)
2372        if (task.name == "finalize")
2373                break
2374        end
2375        task.execute
2376        MSG::debug("Slave '" + mailbox + "' done executing task "+ task.name + ".")
2377     end
2378     MSG::info("I'm done, see you")
2379   end
2380 end
2381 \endverbatim
2382 to receive a task , we use the method <i>MSG::Task.receive(mailbox)</i> that return a MSG:Task object (received task).
2383
2384 \li Main chunk
2385 \verbatim
2386 if (ARGV.length == 2) 
2387         MSG.createEnvironment(ARGV[0])
2388         MSG.deployApplication(ARGV[1])
2389 else 
2390         MSG.createEnvironment("platform.xml")
2391         MSG.deployApplication("deploy.xml")
2392 end
2393 MSG.run
2394 puts "Simulation time : " + MSG.getClock .to_s
2395 MSG.exit
2396 \endverbatim
2397 - <i>MSG.createEnvironment(platform_file)</i> : set up the environment
2398 - <i>MSG.deployApplication(deployment_file)</i> : load the deployment file description.
2399 - <i>MSG.run</i> : run the simulation
2400
2401 \subsubsection faq_binding_ruby_data Exchanging data 
2402 ruby bindings provides two ways to exchange data between ruby processes.
2403 \li MSG::Task.join & MSG::Task.data \br
2404
2405   the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
2406   
2407   -<i>MSG::Task.join</i> : makes possible to join any kind of ruby data within a task.
2408   \verbatim
2409    ...
2410    myTable = Array.new
2411    myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
2412    # Creates and send Task With the Table inside
2413    task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
2414    task.join(myTable);
2415    ...
2416    task.send(mailbox);
2417    \endverbatim
2418    -<i>MSG::Task.data</i> : to access to the data contained into the task.
2419    \verbatim
2420    ...
2421    task = MSG::Task.receive(recv_mailbox.to_s)
2422    table = task.data
2423    quicksort(table,0,table.size-1)
2424    ...
2425    \endverbatim
2426 you can find a complet example illustrating the use of those methods  in file /example/ruby/Quicksort.rb
2427
2428 \li inheritence 
2429  
2430  another 'object-oriented' way to do it , is to make your own 'task' class that inherit from  MSG::Task ,
2431  and contains data you want to deal with , the only 'tricky' thing is that "the initializer" method has no effect ! 
2432  
2433  the use of some getter/setter methods would be the simple way to manage your data  :) 
2434  \verbatim
2435 class PingPongTask < MSG::Task
2436   # The initialize method has no effect 
2437   @time 
2438   def setTime(t)
2439     @time = t
2440   end
2441   def getTime()
2442     return @time
2443   end
2444 end
2445  \endverbatim
2446  you can find an example of use in file example/ruby/PingPong.rb
2447
2448 \section faq_troubleshooting Troubleshooting
2449
2450 \subsection faq_trouble_lib_compil SimGrid compilation and installation problems
2451
2452 \subsubsection faq_trouble_lib_config ./configure fails!
2453
2454 We know only one reason for the configure to fail:
2455
2456  - <b>You are using a broken build environment</b>\n
2457    If symptom is that configure complains about gcc not being able to build
2458    executables, you are probably missing the libc6-dev package. Damn Ubuntu.
2459
2460 If you experience other kind of issue, please get in touch with us. We are
2461 always interested in improving our portability to new systems.
2462
2463 \subsubsection faq_trouble_distcheck Dude! "make check" fails on my machine!
2464
2465 Don't assume we never run this target, because we do. Check
2466 http://bob.loria.fr:8010 if you don't believe us.
2467
2468 There is several reasons which may cause the make check to fail on your
2469 machine:
2470
2471  - <b>You are using a broken libc (probably concerning the contextes)</b>.\n
2472    The symptom is that the "make check" fails within the examples/msg directory.\n
2473    By default, SimGrid uses something called ucontexts. This is part of the
2474    libc, but it's quite undertested. For example, some (old) versions of the
2475    glibc on alpha do not implement these functions, but provide the stubs
2476    (which return ENOSYS: not implemented). It may fool our detection mechanism
2477    and leads to segfaults. There is not much we can do to fix the bug.
2478    A workaround is to compile with --with-context=pthread to avoid
2479    ucontext completely. You'll be a bit more limited in the number
2480    of simulated processes you can start concurrently, but 5000
2481    processes is still enough for most purposes, isn't it?\n
2482    This limitation is the reason why we insist on using this piece of ...
2483    software even if it's so troublesome.\n
2484    <b>=> use --with-pthread on AMD64 architecture that do not have an 
2485    ultra-recent libc.</b>
2486    
2487  - <b>There is a bug in SimGrid we aren't aware of</b>.\n
2488    If none of the above apply, please drop us a mail on the mailing list so
2489    that we can check it out. Make sure to read \ref faq_bugrepport
2490    before you do so.
2491
2492 \subsection faq_trouble_compil User code compilation problems
2493
2494 \subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)"
2495
2496 This is because you are using the log mecanism, but you didn't created
2497 any default category in this file. You should refer to \ref XBT_log
2498 for all the details, but you simply forgot to call one of
2499 XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY().
2500
2501 \subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create"
2502
2503 This indicates that one of the library SimGrid depends on (libpthread
2504 here) was missing on the linking command line. Dependencies of
2505 libsimgrid are expressed directly in the dynamic library, so it's
2506 quite impossible that you see this message when doing dynamic linking. 
2507
2508 If you compile your code statically (and if you use a pthread version
2509 of SimGrid -- see \ref faq_more_processes), you must absolutely
2510 specify <tt>-lpthread</tt> on the linker command line. As usual, this should
2511 come after <tt>-lsimgrid</tt> on this command line.
2512
2513 \subsection faq_trouble_errors Runtime error messages
2514
2515 \subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."
2516
2517 This is because your platform file is too big for the parser. 
2518
2519 Actually, the message comes directly from FleXML, the technology on top of
2520 which the parser is built. FleXML has the bad idea of fetching the whole
2521 document in memory before parsing it. And moreover, the memory buffer size
2522 must be determined at compilation time.
2523
2524 We use a value which seems big enough for our need without bloating the
2525 simulators footprints. But of course your mileage may vary. In this case,
2526 just edit src/surf/surfxml.l modify the definition of
2527 FLEXML_BUFFERSTACKSIZE. E.g.
2528
2529 \verbatim
2530 #define FLEXML_BUFFERSTACKSIZE 1000000000
2531 \endverbatim
2532
2533 Then recompile and everything should be fine, provided that your version of
2534 Flex is recent enough (>= 2.5.31). If not the compilation process should
2535 warn you.
2536
2537 A while ago, we worked on FleXML to reduce a bit its memory consumption, but
2538 these issues remain. There is two things we should do:
2539
2540   - use a dynamic buffer instead of a static one so that the only limit
2541     becomes your memory, not a stupid constant fixed at compilation time
2542     (maybe not so difficult).
2543   - change the parser so that it does not need to get the whole file in
2544     memory before parsing
2545     (seems quite difficult, but I'm a complete newbe wrt flex stuff).
2546
2547 These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
2548 the development of FleXML, I can grant you that any patches would be really
2549 welcome and quickly integrated.
2550
2551 <b>Update:</b> A new version of FleXML (1.7) was released. Most of the work
2552 was done by William Dowling, who use it in his own work. The good point is
2553 that it now use a dynamic buffer, and that the memory usage was greatly
2554 improved. The downside is that William also changed some things internally,
2555 and it breaks the hack we devised to bypass the parser, as explained in 
2556 \ref faq_flexml_bypassing. Indeed, this is not a classical usage of the
2557 parser, and Will didn't imagine that we may have used (and even documented)
2558 such a crude usage of FleXML. So, we now have to repair the bypassing
2559 functionality to use the lastest FleXML version and fix the memory usage in
2560 SimGrid.
2561
2562 \subsubsection faq_trouble_gras_transport GRAS spits networking error messages
2563
2564 Gras, on real platforms, naturally use regular sockets to communicate. They
2565 are deeply hidden in the gras abstraction, but when things go wrong, you may
2566 get some weird error messages. Here are some example, with the probable
2567 reason:
2568
2569  - <b>Transport endpoint is not connected</b>: several processes try to open
2570    a server socket on the same port number of the same machine. This is
2571    naturally bad and each process should pick its own port number for this.\n
2572    Maybe, you just have some processes remaining from a previous experiment 
2573    on your machine.\n
2574    Killing them may help, but again if you kill -KILL them, you'll have to
2575    wait for a while: they didn't close there sockets properly and the system
2576    needs a while to notice that this port is free again.
2577
2578  - <b>Socket closed by remote side</b>: if the remote process is not
2579    supposed to close the socket at this point, it may be dead.
2580    
2581  - <b>Connection reset by peer</b>: I found this on Internet about this
2582    error. I think it's what's happening here, too:\n   
2583    <i>This basically means that a network error occurred while the client was
2584    receiving data from the server. But what is really happening is that the
2585    server actually accepts the connection, processes the request, and sends
2586    a reply to the client. However, when the server closes the socket, the
2587    client believes that the connection has been terminated abnormally
2588    because the socket implementation sends a TCP reset segment telling the
2589    client to throw away the data and report an error.\n
2590    Sometimes, this problem is caused by not properly closing the
2591    input/output streams and the socket connection. Make sure you close the
2592    input/output streams and socket connection properly. If everything is
2593    closed properly, however, and the problem persists, you can work around
2594    it by adding a one-second sleep before closing the streams and the
2595    socket. This technique, however, is not reliable and may not work on all
2596    systems.</i>\n
2597    Since GRAS sockets are closed properly (repeat after me: there is no bug
2598    in GRAS), it is either that you are closing your sockets on server side
2599    before the client get a chance to read them (use gras_os_sleep() to delay
2600    the server), or the server died awfully before the client got the data.
2601
2602 \subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old.
2603
2604 The format of the XML platform description files is sometimes
2605 improved. For example, we decided to change the units used in SimGrid
2606 from MBytes, MFlops and seconds to Bytes, Flops and seconds to ease
2607 people exchanging small messages. We also reworked the route
2608 descriptions to allow more compact descriptions.
2609
2610 That is why the XML files are versionned using the 'version' attribute
2611 of the root tag. Currently, it should read:
2612 \verbatim
2613   <platform version="2">
2614 \endverbatim
2615
2616 If your files are too old, you can use the simgrid_update_xml.pl
2617 script which can be found in the tools directory of the archive.
2618
2619 \subsection faq_trouble_valgrind Valgrind-related and other debugger issues
2620
2621 If you don't, you really should use valgrind to debug your code, it's
2622 almost magic.
2623
2624 \subsubsection faq_trouble_vg_longjmp longjmp madness in valgrind
2625
2626 This is when valgrind starts complaining about longjmp things, just like:
2627
2628 \verbatim ==21434== Conditional jump or move depends on uninitialised value(s)
2629 ==21434==    at 0x420DBE5: longjmp (longjmp.c:33)
2630 ==21434==
2631 ==21434== Use of uninitialised value of size 4
2632 ==21434==    at 0x420DC3A: __longjmp (__longjmp.S:48)
2633 \endverbatim
2634
2635 This is the sign that you didn't used the exception mecanism well. Most
2636 probably, you have a <tt>return;</tt> somewhere within a <tt>TRY{}</tt>
2637 block. This is <b>evil</b>, and you must not do this. Did you read the section
2638 about \ref XBT_ex??
2639
2640 \subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces!
2641
2642 It may happen that valgrind, the memory debugger beloved by any decent C
2643 programmer, spits tons of warnings like the following :
2644 \verbatim ==8414== Conditional jump or move depends on uninitialised value(s)
2645 ==8414==    at 0x400882D: (within /lib/ld-2.3.6.so)
2646 ==8414==    by 0x414EDE9: (within /lib/tls/i686/cmov/libc-2.3.6.so)
2647 ==8414==    by 0x400B105: (within /lib/ld-2.3.6.so)
2648 ==8414==    by 0x414F937: _dl_open (in /lib/tls/i686/cmov/libc-2.3.6.so)
2649 ==8414==    by 0x4150F4C: (within /lib/tls/i686/cmov/libc-2.3.6.so)
2650 ==8414==    by 0x400B105: (within /lib/ld-2.3.6.so)
2651 ==8414==    by 0x415102D: __libc_dlopen_mode (in /lib/tls/i686/cmov/libc-2.3.6.so)
2652 ==8414==    by 0x412D6B9: backtrace (in /lib/tls/i686/cmov/libc-2.3.6.so)
2653 ==8414==    by 0x8076446: xbt_dictelm_get_ext (dict_elm.c:714)
2654 ==8414==    by 0x80764C1: xbt_dictelm_get (dict_elm.c:732)
2655 ==8414==    by 0x8079010: xbt_cfg_register (config.c:208)
2656 ==8414==    by 0x806821B: MSG_config (msg_config.c:42)
2657 \endverbatim
2658
2659 This problem is somewhere in the libc when using the backtraces and there is
2660 very few things we can do ourselves to fix it. Instead, here is how to tell
2661 valgrind to ignore the error. Add the following to your ~/.valgrind.supp (or
2662 create this file on need). Make sure to change the obj line according to
2663 your personnal mileage (change 2.3.6 to the actual version you are using,
2664 which you can retrieve with a simple "ls /lib/ld*.so").
2665
2666 \verbatim {
2667    name: Backtrace madness
2668    Memcheck:Cond
2669    obj:/lib/ld-2.3.6.so
2670    fun:dl_open_worker
2671    fun:_dl_open
2672    fun:do_dlopen
2673    fun:dlerror_run
2674    fun:__libc_dlopen_mode
2675 }\endverbatim
2676
2677 Then, you have to specify valgrind to use this suppression file by passing
2678 the <tt>--suppressions=$HOME/.valgrind.supp</tt> option on the command line.
2679 You can also add the following to your ~/.bashrc so that it gets passed
2680 automatically. Actually, it passes a bit more options to valgrind, and this
2681 happen to be my personnal settings. Check the valgrind documentation for
2682 more information.
2683
2684 \verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" \endverbatim
2685
2686 \subsubsection faq_trouble_backtraces Truncated backtraces
2687
2688 When debugging SimGrid, it's easier to pass the
2689 --disable-compiler-optimization flag to the configure if valgrind or
2690 gdb get fooled by the optimization done by the compiler. But you
2691 should remove these flag when everything works before going in
2692 production (before launching your 1252135 experiments), or everything
2693 will run only one half of the true SimGrid potential.
2694
2695 \subsection faq_deadlock There is a deadlock in my code!!!
2696
2697 Unfortunately, we cannot debug every code written in SimGrid.  We
2698 furthermore believe that the framework provides ways enough
2699 information to debug such informations yourself. If the textual output
2700 is not enough, Make sure to check the \ref faq_visualization FAQ entry to see
2701 how to get a graphical one.
2702
2703 Now, if you come up with a really simple example that deadlocks and
2704 you're absolutely convinced that it should not, you can ask on the
2705 list. Just be aware that you'll be severely punished if the mistake is
2706 on your side... We have plenty of FAQ entries to redact and new
2707 features to implement for the impenitents! ;)
2708
2709 \subsection faq_surf_network_latency I get weird timings when I play with the latencies.
2710
2711 OK, first of all, remember that units should be Bytes, Flops and
2712 Seconds. If you don't use such units, some SimGrid constants (e.g. the
2713 SG_TCP_CTE_GAMMA constant used in most network models) won't have the
2714 right unit and you'll end up with weird results.
2715
2716 Here is what happens with a single transfer of size L on a link
2717 (bw,lat) when nothing else happens.
2718
2719 \verbatim
2720 0-----lat--------------------------------------------------t
2721 |-----|**** real_bw =min(bw,SG_TCP_CTE_GAMMA/(2*lat)) *****|
2722 \endverbatim
2723
2724 In more complex situations, this min is the solution of a complex
2725 max-min linear system.  Have a look 
2726 <a href="http://lists.gforge.inria.fr/pipermail/simgrid-devel/2006-April/thread.html">here</a>
2727 and read the two threads "Bug in SURF?" and "Surf bug not
2728 fixed?". You'll have a few other examples of such computations. You
2729 can also read "A Network Model for Simulation of Grid Application" by
2730 Henri Casanova and Loris Marchal to have all the details. The fact
2731 that the real_bw is smaller than bw is easy to understand. The fact
2732 that real_bw is smaller than SG_TCP_CTE_GAMMA/(2*lat) is due to the
2733 window-based congestion mechanism of TCP. With TCP, you can't exploit
2734 your huge network capacity if you don't have a good round-trip-time
2735 because of the acks...
2736
2737 Anyway, what you get is t=lat + L/min(bw,SG_TCP_CTE_GAMMA/(2*lat)).
2738
2739   * if I you set (bw,lat)=(100 000 000, 0.00001), you get t =  1.00001 (you fully
2740 use your link)
2741   * if I you set (bw,lat)=(100 000 000, 0.0001),  you get t =  1.0001 (you're on the
2742 limit)
2743   * if I you set (bw,lat)=(100 000 000, 0.001),   you get t = 10.001  (ouch!)
2744
2745 This bound on the effective bandwidth of a flow is not the only thing
2746 that may make your result be unexpected. For example, two flows
2747 competing on a saturated link receive an amount of bandwidth inversely
2748 proportional to their round trip time.
2749
2750 \subsection faq_bugrepport So I've found a bug in SimGrid. How to report it?
2751
2752 We do our best to make sure to hammer away any bugs of SimGrid, but this is
2753 still an academic project so please be patient if/when you find bugs in it.
2754 If you do, the best solution is to drop an email either on the simgrid-user
2755 or the simgrid-devel mailing list and explain us about the issue.  You can
2756 also decide to open a formal bug report using the
2757 <a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">relevant
2758 interface</a>. You need to login on the server to get the ability to submit
2759 bugs. 
2760
2761 We will do our best to solve any problem repported, but you need to help us
2762 finding the issue. Just telling "it segfault" isn't enough. Telling "It
2763 segfaults when running the attached simulator" doesn't really help either.
2764 You may find the following article interesting to see how to repport
2765 informative bug repports:
2766 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid
2767 specific at all, but it's full of good advices).
2768
2769 \author Arnaud Legrand (arnaud.legrand::imag.fr)
2770 \author Martin Quinson (martin.quinson::loria.fr)
2771
2772
2773 */
2774
2775 ******************************************************************
2776 *              OLD CRUFT NOT USED ANYMORE                        *
2777 ******************************************************************
2778
2779
2780 \subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
2781
2782 At the moment, we do not distribute Windows pre-compiled version of SimGrid
2783 because the support for this platform is still experimental. We know that
2784 some parts of the GRAS environment do not work, and we think that the others
2785 environments (MSG and SD) have good chances to work, but we didn't test
2786 ourselves. This section explains how we generate the SimGrid DLL so that you
2787 can build it for yourself. First of all, you need to have a version more
2788 recent than 3.1 (ie, a SVN version as time of writting).
2789
2790 In order to cross-compile the package to windows from linux, you need to
2791 install mingw32 (minimalist gnu win32). On Debian, you can do so by
2792 installing the packages mingw32 (compiler), mingw32-binutils (linker and
2793 so), mingw32-runtime.
2794
2795 You can use the VPATH support of configure to compile at the same time for
2796 linux and windows without dupplicating the source nor cleaning the tree
2797 between each. Just run bootstrap (if you use the SVN) to run the autotools.
2798 Then, create a linux and a win directories. Then, type:
2799 \verbatim  cd linux; ../configure --srcdir=.. <usual configure flags>; make; cd ..
2800 cd win;  ../configure --srcdir=.. --host=i586-mingw32msvc <flags>; make; cd ..
2801 \endverbatim
2802 The trick to VPATH builds is to call configure from another directory,
2803 passing it an extra --srcdir argument to tell it where all the sources are.
2804 It will understand you want to use VPATH. Then, the trick to cross-compile
2805 is simply to add a --host argument specifying the target you want to build
2806 for. The i586-mingw32msvc string is what you have to pass to use the mingw32
2807 environment as distributed in Debian.
2808
2809 After that, you can run all make targets from both directories, and test
2810 easily that what you change for one arch does not break the other one. 
2811
2812 It is possible that this VPATH build thing breaks from time to time in the
2813 SVN since it's quite fragile, but it's granted to work in any released
2814 version. If you experience problems, drop us a mail. 
2815
2816 Another possible source of issue is that at the moment, building the
2817 examples request to use the gras_stub_generator tool, which is a compiled
2818 program, not a script. In cross-compilation, you need to cross-execute with
2819 wine for example, which is not really pleasant. We are working on this, but
2820 in the meanwhile, simply don't build the examples in cross-compilation
2821 (<tt>cd src</tt> before running make).
2822     
2823 Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be
2824 usable. For example, if you want to test your build with wine, you should do
2825 the following to put this library where wine looks for DLLs.
2826 \verbatim 
2827 cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/
2828 gunzip ~/.wine/c/windows/system/mingwm10.dll.gz
2829 \endverbatim
2830
2831 The DLL is built in src/.libs, and installed in the <i>prefix</i>/bin directory
2832 when you run make install. 
2833
2834 If you want to use it in a native project on windows, you need to use 
2835 simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file
2836 under linux (listing the defined symbols), and convert it into a .lib file
2837 under windows (specifying this in a way that windows compilers like). To
2838 generate the def files, run (under linux):
2839 \verbatim echo "LIBRARY libsimgrid-0.dll" > simgrid.def
2840 echo EXPORTS >> simgrid.def
2841 nm libsimgrid-0.dll | grep ' T _' | sed 's/.* T _//' >> simgrid.def
2842 nm libsimgrid-0.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> simgrid.def
2843
2844 echo "LIBRARY mingwm10.dll" > mingwm10.def
2845 echo EXPORTS >> mingwm10.def
2846 nm mingwm10.dll | grep ' T _' | sed 's/.* T _//' >> mingwm10.def
2847 nm mingwm10.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> mingwm10.def
2848 \endverbatim
2849
2850 To create the import .lib files, use the <tt>lib</tt> windows tool (from
2851 MSVC) the following way to produce simgrid.lib and mingwm10.lib
2852 \verbatim lib /def:simgrid.def
2853 lib /def:mingwm10.def
2854 \endverbatim
2855
2856 If you happen to use Borland C Builder, the right command line is the
2857 following (note that you don't need any file.def to get this working).
2858 \verbatim implib simgrid.lib libsimgrid-0.dll
2859 implib mingwm10.lib mingwm10.dll
2860 \endverbatim
2861
2862 Then, set the following parameters in Visual C++ 2005:
2863 Linker -> Input -> Additional dependencies = simgrid.lib mingwm10.lib
2864
2865 Just in case you wonder how to generate a DLL from libtool in another
2866 project, we added -no-undefined to any lib*_la_LDFLAGS variables so that
2867 libtool accepts to generate a dynamic library under windows. Then, to make
2868 it true, we pass any dependencies (such as -lws2 under windows or -lpthread
2869 on need) on the linking line. Passing such deps is a good idea anyway so
2870 that they get noted in the library itself, avoiding the users to know about
2871 our dependencies and put them manually on their compilation line. Then we
2872 added the AC_LIBTOOL_WIN32_DLL macro just before AC_PROG_LIBTOOL in the
2873 configure.ac. It means that we exported any symbols which need to be.
2874 Nowadays, functions get automatically exported, so we don't need to load our
2875 header files with tons of __declspec(dllexport) cruft. We only need to do so
2876 for data, but there is no public data in SimGrid so we are good.
2877