1 /*! \page FAQ Frequently Asked Questions
4 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
6 You are at the right place... Having a look to these
7 <a href="http://www.loria.fr/~quinson/blog/2010/06/28/Tutorial_at_HPCS/">the slides of the HPCS'10 tutorial</a>
8 (or to these <a href="http://graal.ens-lyon.fr/~alegrand/articles/slides_g5k_simul.pdf">ancient
9 slides</a>, or to these
10 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">"obsolete" slides</a>)
11 may give you some insights on what SimGrid can help you to do and what
12 are its limitations. Then you definitely should read the \ref
15 If you are stuck at any point and if this FAQ cannot help you, please drop us a
16 mail to the user mailing list: <simgrid-user@lists.gforge.inria.fr>.
18 \subsection faq_interfaces What is the difference between MSG, SimDag, and GRAS? Do they serve the same purpose?
20 It depend on how you define "purpose", I guess ;)
22 They all allow you to build a prototype of application which you can run
23 within the simulator afterward. They all share the same simulation kernel,
24 which is the core of the SimGrid project. They differ by the way you express
27 With SimDag, you express your code as a collection of interdependent
28 parallel tasks. So, in this model, applications can be seen as a DAG of
29 tasks. This is the interface of choice for people wanting to port old
30 code designed for SimGrid v1 or v2 to the framework current version.
32 With both GRAS and MSG, your application is seen as a set of communicating
33 processes, exchanging data by the way of messages and performing computation
36 The difference between both is that MSG is somehow easier to use, but GRAS
37 is not limited to the simulator. Once you're done writing your GRAS code,
38 you can run your code both in the simulator and on a real platform. For this,
39 there are two implementations of the GRAS interface, one for simulation, and one
40 for real execution. So, you just have to relink your code to choose one of
43 \subsection faq_visualization Visualizing and analyzing the results
45 It is sometime convenient to "see" how the agents are behaving. If you
46 like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
47 as a filter to your MSG outputs. It works directly with INFO. Beware,
48 INFO() prints on stderr. Do not forget to redirect if you want to
49 filter (e.g. with bash):
51 ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
54 We also have a more graphical output. Have a look at section \ref options_tracing.
56 \subsection faq_C Argh! Do I really have to code in C?
58 Currently bindings on top of MSG are supported for Java, Ruby and Lua. You can find a few
59 documentation about them on the doc page. Note that bindings are released separately from the main dist
60 and so have their own version numbers.
62 Moreover If you use C++,
63 you should be able to use the SimGrid library as a standard C library
64 and everything should work fine (simply <i>link</i> against this
65 library; recompiling SimGrid with a C++ compiler won't work and it
66 wouldn't help if you could).
69 we do not feel a real demand for any other language. But if you think there is one,
72 \section faq_howto Feature related questions
74 \subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
76 Here is the deal. The whole SimGrid project (MSG, SURF, GRAS, ...) is
77 meant to be kept as simple and generic as possible. We cannot add
78 functions for everybody's needs when these functions can easily be
79 built from the ones already in the API. Most of the time, it is
80 possible and when it was not possible we always have upgraded the API
81 accordingly. When somebody asks us a question like "How to do that?
82 Is there a function in the API to simply do this?", we're always glad
83 to answer and help. However if we don't need this code for our own
84 need, there is no chance we're going to write it... it's your job! :)
85 The counterpart to our answers is that once you come up with a neat
86 implementation of this feature (task duplication, RPC, thread
87 synchronization, ...), you should send it to us and we will be glad to
88 add it to the distribution. Thus, other people will take advantage of
89 it (and we don't have to answer this question again and again ;).
91 You'll find in this section a few "Missing In Action" features. Many
92 people have asked about it and we have given hints on how to simply do
93 it with MSG. Feel free to contribute...
95 \subsection faq_MIA_MSG MSG features
97 \subsubsection faq_MIA_examples I want some more complex MSG examples!
99 Many people have come to ask me a more complex example and each time,
100 they have realized afterward that the basics were in the previous three
103 Of course they have often been needing more complex functions like
104 MSG_process_suspend(), MSG_process_resume() and
105 MSG_process_isSuspended() (to perform synchronization), or
106 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
107 receptions), or even MSG_process_create() (to design asynchronous
108 communications or computations). But the examples are sufficient to
111 We know. We should add some more examples, but not really some more
112 complex ones... We should add some examples that illustrate some other
113 functionalists (like how to simply encode asynchronous
114 communications, RPC, process migrations, thread synchronization, ...)
115 and we will do it when we will have a little bit more time. We have
116 tried to document the examples so that they are understandable. Tell
117 us if something is not clear and once again feel free to participate!
120 \subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication
122 There is no task duplication in MSG. When you create a task, you can
123 process it or send it somewhere else. As soon as a process has sent
124 this task, he doesn't have this task anymore. It's gone. The receiver
125 process has got the task. However, you could decide upon receiving to
126 create a "copy" of a task but you have to handle by yourself the
127 semantic associated to this "duplication".
129 As we already told, we prefer keeping the API as simple as
130 possible. This kind of feature is rather easy to implement by users
131 and the semantic you associate really depends on people. Having a
132 *generic* task duplication mechanism is not that trivial (in
133 particular because of the data field). That is why I would recommend
134 that you write it by yourself even if I can give you advice on how to
137 You have the following functions to get information about a task:
138 MSG_task_get_name(), MSG_task_get_compute_duration(),
139 MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
140 and MSG_task_get_data().
142 You could use a dictionary (#xbt_dict_t) of dynars (#xbt_dynar_t). If
143 you still don't see how to do it, please come back to us...
145 \subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
147 In the past (version <= 3.4), there was no function to perform asynchronous communications.
148 It could easily be implemented by creating new process when needed though. Since version 3.5,
149 we have introduced the following functions:
158 We refer you to the description of these functions for more details on their usage as well
159 as to the example section on \ref MSG_ex_asynchronous_communications.
161 \subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
163 You obviously cannot use pthread_mutexes of pthread_conds since we handle every
164 scheduling related decision within SimGrid.
166 In the past (version <=3.3.4) you could do it by playing with
167 MSG_process_suspend() and MSG_process_resume() or with fake communications (using MSG_task_get(),
168 MSG_task_put() and MSG_task_Iprobe()).
170 Since version 3.4, you can use classical synchronization structures. See page \ref XBT_synchro or simply check in
171 include/xbt/synchro_core.h.
173 \subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
175 There is no such thing because its semantic wouldn't be really
176 clear. Of course, it is something about the amount of host throughput,
177 but there is as many definition of "host load" as people asking for
178 this function. First, you have to remember that resource availability
179 may vary over time, which make any load notion harder to define.
181 It may be instantaneous value or an average one. Moreover it may be only the
182 power of the computer, or may take the background load into account, or may
183 even take the currently running tasks into account. In some SURF models,
184 communications have an influence on computational power. Should it be taken
187 First of all, it's near to impossible to predict the load beforehand in the
188 simulator since it depends on too much parameters (background load
189 variation, bandwidth sharing algorithmic complexity) some of them even being
190 not known beforehand (other task starting at the same time). So, getting
191 this information is really hard (just like in real life). It's not just that
192 we want MSG to be as painful as real life. But as it is in some way
193 realistic, we face some of the same problems as we would face in real life.
195 How would you do it for real? The most common option is to use something
196 like NWS that performs active probes. The best solution is probably to do
197 the same within MSG, as in next code snippet. It is very close from what you
198 would have to do out of the simulator, and thus gives you information that
199 you could also get in real settings to not hinder the realism of your
203 double get_host_load() {
204 m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
205 double date = MSG_get_clock();
207 MSG_task_execute(task);
208 date = MSG_get_clock() - date;
209 MSG_task_destroy(task);
214 Of course, it may not match your personal definition of "host load". In this
215 case, please detail what you mean on the mailing list, and we will extend
216 this FAQ section to fit your taste if possible.
218 \subsubsection faq_MIA_communication_time How can I get the *real* communication time?
220 Communications are synchronous and thus if you simply get the time
221 before and after a communication, you'll only get the transmission
222 time and the time spent to really communicate (it will also take into
223 account the time spent waiting for the other party to be
224 ready). However, getting the *real* communication time is not really
225 hard either. The following solution is a good starting point.
230 m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size,
231 calloc(1,sizeof(double)));
232 *((double*) task->data) = MSG_get_clock();
233 MSG_task_put(task, slaves[i % slaves_count], PORT_22);
234 XBT_INFO("Send completed");
239 m_task_t task = NULL;
242 time1 = MSG_get_clock();
243 a = MSG_task_get(&(task), PORT_22);
244 time2 = MSG_get_clock();
245 if(time1<*((double *)task->data))
246 time1 = *((double *) task->data);
247 XBT_INFO("Communication time : \"%f\" ", time2-time1);
249 MSG_task_destroy(task);
254 \subsection faq_MIA_SimDag SimDag related questions
256 \subsubsection faq_SG_comm Implementing communication delays between tasks.
258 A classic question of SimDag newcomers is about how to express a
259 communication delay between tasks. The thing is that in SimDag, both
260 computation and communication are seen as tasks. So, if you want to
261 model a data dependency between two DAG tasks t1 and t2, you have to
262 create 3 SD_tasks: t1, t2 and c and add dependencies in the following
266 SD_task_dependency_add(NULL, NULL, t1, c);
267 SD_task_dependency_add(NULL, NULL, c, t2);
270 This way task t2 cannot start before the termination of communication c
271 which in turn cannot start before t1 ends.
273 When creating task c, you have to associate an amount of data (in bytes)
274 corresponding to what has to be sent by t1 to t2.
276 Finally to schedule the communication task c, you have to build a list
277 comprising the workstations on which t1 and t2 are scheduled (w1 and w2
278 for example) and build a communication matrix that should look like
281 \subsubsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs.
283 Distributed is somehow "contagious". If you start making distributed
284 decisions, there is no way to handle DAGs directly anymore (unless I
285 am missing something). You have to encode your DAGs in term of
286 communicating process to make the whole scheduling process
287 distributed. Here is an example of how you could do that. Assume T1
288 has to be done before T2.
291 int your_agent(int argc, char *argv[] {
293 T1 = MSG_task_create(...);
294 T2 = MSG_task_create(...);
298 if(cond) MSG_task_execute(T1);
300 if((MSG_task_get_remaining_computation(T1)=0.0) && (you_re_in_a_good_mood))
303 /* do something else */
309 If you decide that the distributed part is not that much important and that
310 DAG is really the level of abstraction you want to work with, then you should
311 give a try to \ref SD_API.
313 \subsection faq_MIA_generic Generic features
315 \subsubsection faq_more_processes Increasing the amount of simulated processes
317 Here are a few tricks you can apply if you want to increase the amount
318 of processes in your simulations.
320 - <b>A few thousands of simulated processes</b> (soft tricks)\n
321 SimGrid can use either pthreads library or the UNIX98 contexts. On
322 most systems, the number of pthreads is limited and then your
323 simulation may be limited for a stupid reason. This is especially
324 true with the current linux pthreads, and I cannot get more than
325 2000 simulated processes with pthreads on my box. The UNIX98
326 contexts allow me to raise the limit to 25,000 simulated processes
328 The <tt>--with-context</tt> option of the <tt>./configure</tt>
329 script allows you to choose between UNIX98 contexts
330 (<tt>--with-context=ucontext</tt>) and the pthread version
331 (<tt>--with-context=pthread</tt>). The default value is ucontext
332 when the script detect a working UNIX98 context implementation. On
333 Windows boxes, the provided value is discarded and an adapted
334 version is picked up.\n\n
335 We experienced some issues with contexts on some rare systems
336 (solaris 8 and lower or old alpha linuxes comes to mind). The main
337 problem is that the configure script detect the contexts as being
338 functional when it's not true. If you happen to use such a system,
339 switch manually to the pthread version, and provide us with a good
340 patch for the configure script so that it is done automatically ;)
342 - <b>Hundred thousands of simulated processes</b> (hard-core tricks)\n
343 As explained above, SimGrid can use UNIX98 contexts to represent
344 and handle the simulated processes. Thanks to this, the main
345 limitation to the number of simulated processes becomes the
346 available memory.\n\n
347 Here are some tricks I had to use in order to run a token ring
348 between 25,000 processes on my laptop (1Gb memory, 1.5Gb swap).\n
349 - First of all, make sure your code runs for a few hundreds
350 processes before trying to push the limit. Make sure it's
351 valgrind-clean, i.e. that valgrind does not report neither memory
352 error nor memory leaks. Indeed, numerous simulated processes
353 result in *fat* simulation hindering debugging.
354 - It was really boring to write 25,000 entries in the deployment
355 file, so I wrote a little script
356 <tt>examples/gras/mutual_exclusion/simple_token/make_deployment.pl</tt>, which you may
357 want to adapt to your case. You could also think about hijacking
358 the SURFXML parser (have look at \ref pf_flexml_bypassing).
359 - The deployment file became quite big, so I had to do what is in
360 the FAQ entry \ref faq_flexml_limit
361 - Each UNIX98 context has its own stack entry. As debugging this is
362 quite hairy, the default value is a bit overestimated so that
363 user doesn't get into trouble about this. You want to tune this
364 size to increase the number of processes. This is the
365 <tt>STACK_SIZE</tt> define in
366 <tt>src/xbt/xbt_context_sysv.c</tt>, which is 128kb by default.
367 Reduce this as much as you can, but be warned that if this value
368 is too low, you'll get a segfault. The token ring example, which
369 is quite simple, runs with 40kb stacks.
370 - You may tweak the logs to reduce the stack size further. When
371 logging something, we try to build the string to display in a
372 char array on the stack. The size of this array is constant (and
373 equal to XBT_LOG_BUFF_SIZE, defined in include/xbt/log/h). If the
374 string is too large to fit this buffer, we move to a dynamically
375 sized buffer. In which case, we have to traverse one time the log
376 event arguments to compute the size we need for the buffer,
377 malloc it, and traverse the argument list again to do the actual
379 The idea here is to move XBT_LOG_BUFF_SIZE to 1, forcing the logs
380 to use a dynamic array each time. This allows us to lower further
381 the stack size at the price of some performance loss...\n
382 This allowed me to run the reduce the stack size to ... 4k. Ie,
383 on my 1Gb laptop, I can run more than 250,000 processes!
385 \subsubsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid?
387 No, there is no native support for batch schedulers and none is
388 planned because this is a very specific need (and doing it in a
389 generic way is thus very hard). However some people have implemented
390 their own batch schedulers. Vincent Garonne wrote one during his PhD
391 and put his code in the contrib directory of our SVN so that other can
392 keep working on it. You may find inspiring ideas in it.
394 \subsubsection faq_MIA_checkpointing I need a checkpointing thing
396 Actually, it depends on whether you want to checkpoint the simulation, or to
397 simulate checkpoints.
399 The first one could help if your simulation is a long standing process you
400 want to keep running even on hardware issues. It could also help to
401 <i>rewind</i> the simulation by jumping sometimes on an old checkpoint to
402 cancel recent calculations.\n
403 Unfortunately, such thing will probably never exist in SG. One would have to
404 duplicate all data structures because doing a rewind at the simulator level
405 is very very hard (not talking about the malloc free operations that might
406 have been done in between). Instead, you may be interested in the Libckpt
407 library (http://www.cs.utk.edu/~plank/plank/www/libckpt.html). This is the
408 checkpointing solution used in the condor project, for example. It makes it
409 easy to create checkpoints (at the OS level, creating something like core
410 files), and rerunning them on need.
412 If you want to simulate checkpoints instead, it means that you want the
413 state of an executing task (in particular, the progress made towards
414 completion) to be saved somewhere. So if a host (and the task executing on
415 it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted
416 from the last checkpoint.\n
418 Actually, such a thing does not exist in SimGrid either, but it's just
419 because we don't think it is fundamental and it may be done in the user code
420 at relatively low cost. You could for example use a watcher that
421 periodically get the remaining amount of things to do (using
422 MSG_task_get_remaining_computation()), or fragment the task in smaller
425 \subsection faq_platform Platform building and Dynamic resources
427 \subsubsection faq_platform_example Where can I find SimGrid platform files?
429 There are several little examples in the archive, in the examples/msg
430 directory. From time to time, we are asked for other files, but we
431 don't have much at hand right now.
433 You should refer to the Platform Description Archive
434 (http://pda.gforge.inria.fr) project to see the other platform file we
435 have available, as well as the Simulacrum simulator, meant to generate
436 SimGrid platforms using all classical generation algorithms.
438 \subsubsection faq_platform_alnem How can I automatically map an existing platform?
440 We are working on a project called ALNeM (Application-Level Network
441 Mapper) which goal is to automatically discover the topology of an
442 existing network. Its output will be a platform description file
443 following the SimGrid syntax, so everybody will get the ability to map
444 their own lab network (and contribute them to the catalog project).
445 This tool is not ready yet, but it move quite fast forward. Just stay
448 \subsubsection faq_platform_synthetic Generating synthetic but realistic platforms
450 The third possibility to get a platform file (after manual or
451 automatic mapping of real platforms) is to generate synthetic
452 platforms. Getting a realistic result is not a trivial task, and
453 moreover, nobody is really able to define what "realistic" means when
454 speaking of topology files. You can find some more thoughts on this
456 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
458 If you are looking for an actual tool, there we have a little tool to
459 annotate Tiers-generated topologies. This perl-script is in
460 <tt>tools/platform_generation/</tt> directory of the SVN. Dinda et Al.
461 released a very comparable tool, and called it GridG.
464 The specified computing power will be available to up to 6 sequential
465 tasks without sharing. If more tasks are placed on this host, the
466 resource will be shared accordingly. For example, if you schedule 12
467 tasks on the host, each will get half of the computing power. Please
468 note that although sound, this model were never scientifically
469 assessed. Please keep this fact in mind when using it.
474 \section faq_troubleshooting Troubleshooting
476 \subsection faq_trouble_lib_compil SimGrid compilation and installation problems
478 \subsubsection faq_trouble_lib_config cmake fails!
480 We know only one reason for the configure to fail:
482 - <b>You are using a broken build environment</b>\n
483 If symptom is that the configury magic complains about gcc not being able to build
484 executables, you are probably missing the libc6-dev package. Damn Ubuntu.
486 If you experience other kind of issue, please get in touch with us. We are
487 always interested in improving our portability to new systems.
489 \subsubsection faq_trouble_distcheck Dude! "ctest" fails on my machine!
491 Don't assume we never run this target, because we do. Check
492 http://cdash.inria.fr/CDash/index.php?project=Simgrid (click on
493 previous if there is no result for today: results are produced only by
494 11am, French time) and
495 https://buildd.debian.org/status/logs.php?pkg=simgrid if you don't believe us.
497 If it's failing on your machine in a way not experienced by the
498 autobuilders above, please drop us a mail on the mailing list so that
499 we can check it out. Make sure to read \ref faq_bugrepport before you
502 \subsection faq_trouble_compil User code compilation problems
504 \subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)"
506 This is because you are using the log mecanism, but you didn't created
507 any default category in this file. You should refer to \ref XBT_log
508 for all the details, but you simply forgot to call one of
509 XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY().
511 \subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create"
513 This indicates that one of the library SimGrid depends on (libpthread
514 here) was missing on the linking command line. Dependencies of
515 libsimgrid are expressed directly in the dynamic library, so it's
516 quite impossible that you see this message when doing dynamic linking.
518 If you compile your code statically (and if you use a pthread version
519 of SimGrid -- see \ref faq_more_processes), you must absolutely
520 specify <tt>-lpthread</tt> on the linker command line. As usual, this should
521 come after <tt>-lsimgrid</tt> on this command line.
523 \subsubsection faq_trouble_lib_msg_deprecated "gcc: undefined reference to MSG_*"
525 Since version 3.7 all the m_channel_t mecanism is deprecated. So functions
526 about this mecanism may get removed in future releases.
530 \li XBT_PUBLIC(int) MSG_get_host_number(void);
532 \li XBT_PUBLIC(m_host_t *) MSG_get_host_table(void);
534 \li XBT_PUBLIC(MSG_error_t) MSG_get_errno(void);
536 \li XBT_PUBLIC(MSG_error_t) MSG_task_get(m_task_t * task, m_channel_t channel);
538 \li XBT_PUBLIC(MSG_error_t) MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel, double max_duration);
540 \li XBT_PUBLIC(MSG_error_t) MSG_task_get_from_host(m_task_t * task, int channel, m_host_t host);
542 \li XBT_PUBLIC(MSG_error_t) MSG_task_get_ext(m_task_t * task, int channel, double max_duration, m_host_t host);
544 \li XBT_PUBLIC(MSG_error_t) MSG_task_put(m_task_t task, m_host_t dest, m_channel_t channel);
546 \li XBT_PUBLIC(MSG_error_t) MSG_task_put_bounded(m_task_t task, m_host_t dest, m_channel_t channel, double max_rate);
548 \li XBT_PUBLIC(MSG_error_t) MSG_task_put_with_timeout(m_task_t task, m_host_t dest, m_channel_t channel, double max_duration);
550 \li XBT_PUBLIC(int) MSG_task_Iprobe(m_channel_t channel);
552 \li XBT_PUBLIC(int) MSG_task_probe_from(m_channel_t channel);
554 \li XBT_PUBLIC(int) MSG_task_probe_from_host(int channel, m_host_t host);
556 \li XBT_PUBLIC(MSG_error_t) MSG_set_channel_number(int number);
558 \li XBT_PUBLIC(int) MSG_get_channel_number(void);
560 If you want them you have to compile Simgrid v3.7 with option "-Denable_msg_deprecated=ON".
561 Using them should print warning to inform what new function you have to use.
563 \subsection faq_trouble_errors Runtime error messages
565 \subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."
567 This is because your platform file is too big for the parser.
569 Actually, the message comes directly from FleXML, the technology on top of
570 which the parser is built. FleXML has the bad idea of fetching the whole
571 document in memory before parsing it. And moreover, the memory buffer size
572 must be determined at compilation time.
574 We use a value which seems big enough for our need without bloating the
575 simulators footprints. But of course your mileage may vary. In this case,
576 just edit src/surf/surfxml.l modify the definition of
577 FLEXML_BUFFERSTACKSIZE. E.g.
580 #define FLEXML_BUFFERSTACKSIZE 1000000000
583 Then recompile and everything should be fine, provided that your version of
584 Flex is recent enough (>= 2.5.31). If not the compilation process should
587 A while ago, we worked on FleXML to reduce a bit its memory consumption, but
588 these issues remain. There is two things we should do:
590 - use a dynamic buffer instead of a static one so that the only limit
591 becomes your memory, not a stupid constant fixed at compilation time
592 (maybe not so difficult).
593 - change the parser so that it does not need to get the whole file in
594 memory before parsing
595 (seems quite difficult, but I'm a complete newbe wrt flex stuff).
597 These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
598 the development of FleXML, I can grant you that any patches would be really
599 welcome and quickly integrated.
601 <b>Update:</b> A new version of FleXML (1.7) was released. Most of the work
602 was done by William Dowling, who use it in his own work. The good point is
603 that it now use a dynamic buffer, and that the memory usage was greatly
604 improved. The downside is that William also changed some things internally,
605 and it breaks the hack we devised to bypass the parser, as explained in
606 \ref pf_flexml_bypassing. Indeed, this is not a classical usage of the
607 parser, and Will didn't imagine that we may have used (and even documented)
608 such a crude usage of FleXML. So, we now have to repair the bypassing
609 functionality to use the lastest FleXML version and fix the memory usage in
612 \subsubsection faq_trouble_gras_transport GRAS spits networking error messages
614 Gras, on real platforms, naturally use regular sockets to communicate. They
615 are deeply hidden in the gras abstraction, but when things go wrong, you may
616 get some weird error messages. Here are some example, with the probable
619 - <b>Transport endpoint is not connected</b>: several processes try to open
620 a server socket on the same port number of the same machine. This is
621 naturally bad and each process should pick its own port number for this.\n
622 Maybe, you just have some processes remaining from a previous experiment
624 Killing them may help, but again if you kill -KILL them, you'll have to
625 wait for a while: they didn't close there sockets properly and the system
626 needs a while to notice that this port is free again.
628 - <b>Socket closed by remote side</b>: if the remote process is not
629 supposed to close the socket at this point, it may be dead.
631 - <b>Connection reset by peer</b>: I found this on Internet about this
632 error. I think it's what's happening here, too:\n
633 <i>This basically means that a network error occurred while the client was
634 receiving data from the server. But what is really happening is that the
635 server actually accepts the connection, processes the request, and sends
636 a reply to the client. However, when the server closes the socket, the
637 client believes that the connection has been terminated abnormally
638 because the socket implementation sends a TCP reset segment telling the
639 client to throw away the data and report an error.\n
640 Sometimes, this problem is caused by not properly closing the
641 input/output streams and the socket connection. Make sure you close the
642 input/output streams and socket connection properly. If everything is
643 closed properly, however, and the problem persists, you can work around
644 it by adding a one-second sleep before closing the streams and the
645 socket. This technique, however, is not reliable and may not work on all
647 Since GRAS sockets are closed properly (repeat after me: there is no bug
648 in GRAS), it is either that you are closing your sockets on server side
649 before the client get a chance to read them (use gras_os_sleep() to delay
650 the server), or the server died awfully before the client got the data.
652 \subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old.
654 The format of the XML platform description files is sometimes
655 improved. For example, we decided to change the units used in SimGrid
656 from MBytes, MFlops and seconds to Bytes, Flops and seconds to ease
657 people exchanging small messages. We also reworked the route
658 descriptions to allow more compact descriptions.
660 That is why the XML files are versionned using the 'version' attribute
661 of the root tag. Currently, it should read:
663 <platform version="2">
666 If your files are too old, you can use the simgrid_update_xml.pl
667 script which can be found in the tools directory of the archive.
669 \subsection faq_trouble_valgrind Valgrind-related and other debugger issues
671 If you don't, you really should use valgrind to debug your code, it's
674 \subsubsection faq_trouble_vg_longjmp longjmp madness in valgrind
676 This is when valgrind starts complaining about longjmp things, just like:
678 \verbatim ==21434== Conditional jump or move depends on uninitialised value(s)
679 ==21434== at 0x420DBE5: longjmp (longjmp.c:33)
681 ==21434== Use of uninitialised value of size 4
682 ==21434== at 0x420DC3A: __longjmp (__longjmp.S:48)
685 This is the sign that you didn't used the exception mecanism well. Most
686 probably, you have a <tt>return;</tt> somewhere within a <tt>TRY{}</tt>
687 block. This is <b>evil</b>, and you must not do this. Did you read the section
690 \subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces!
692 It may happen that valgrind, the memory debugger beloved by any decent C
693 programmer, spits tons of warnings like the following :
694 \verbatim ==8414== Conditional jump or move depends on uninitialised value(s)
695 ==8414== at 0x400882D: (within /lib/ld-2.3.6.so)
696 ==8414== by 0x414EDE9: (within /lib/tls/i686/cmov/libc-2.3.6.so)
697 ==8414== by 0x400B105: (within /lib/ld-2.3.6.so)
698 ==8414== by 0x414F937: _dl_open (in /lib/tls/i686/cmov/libc-2.3.6.so)
699 ==8414== by 0x4150F4C: (within /lib/tls/i686/cmov/libc-2.3.6.so)
700 ==8414== by 0x400B105: (within /lib/ld-2.3.6.so)
701 ==8414== by 0x415102D: __libc_dlopen_mode (in /lib/tls/i686/cmov/libc-2.3.6.so)
702 ==8414== by 0x412D6B9: backtrace (in /lib/tls/i686/cmov/libc-2.3.6.so)
703 ==8414== by 0x8076446: xbt_dictelm_get_ext (dict_elm.c:714)
704 ==8414== by 0x80764C1: xbt_dictelm_get (dict_elm.c:732)
705 ==8414== by 0x8079010: xbt_cfg_register (config.c:208)
706 ==8414== by 0x806821B: MSG_config (msg_config.c:42)
709 This problem is somewhere in the libc when using the backtraces and there is
710 very few things we can do ourselves to fix it. Instead, here is how to tell
711 valgrind to ignore the error. Add the following to your ~/.valgrind.supp (or
712 create this file on need). Make sure to change the obj line according to
713 your personnal mileage (change 2.3.6 to the actual version you are using,
714 which you can retrieve with a simple "ls /lib/ld*.so").
717 name: Backtrace madness
724 fun:__libc_dlopen_mode
727 Then, you have to specify valgrind to use this suppression file by passing
728 the <tt>--suppressions=$HOME/.valgrind.supp</tt> option on the command line.
729 You can also add the following to your ~/.bashrc so that it gets passed
730 automatically. Actually, it passes a bit more options to valgrind, and this
731 happen to be my personnal settings. Check the valgrind documentation for
734 \verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" \endverbatim
736 \subsubsection faq_trouble_backtraces Truncated backtraces
738 When debugging SimGrid, it's easier to pass the
739 --disable-compiler-optimization flag to the configure if valgrind or
740 gdb get fooled by the optimization done by the compiler. But you
741 should remove these flag when everything works before going in
742 production (before launching your 1252135 experiments), or everything
743 will run only one half of the true SimGrid potential.
745 \subsection faq_deadlock There is a deadlock in my code!!!
747 Unfortunately, we cannot debug every code written in SimGrid. We
748 furthermore believe that the framework provides ways enough
749 information to debug such informations yourself. If the textual output
750 is not enough, Make sure to check the \ref faq_visualization FAQ entry to see
751 how to get a graphical one.
753 Now, if you come up with a really simple example that deadlocks and
754 you're absolutely convinced that it should not, you can ask on the
755 list. Just be aware that you'll be severely punished if the mistake is
756 on your side... We have plenty of FAQ entries to redact and new
757 features to implement for the impenitents! ;)
759 \subsection faq_surf_network_latency I get weird timings when I play with the latencies.
761 OK, first of all, remember that units should be Bytes, Flops and
762 Seconds. If you don't use such units, some SimGrid constants (e.g. the
763 SG_TCP_CTE_GAMMA constant used in most network models) won't have the
764 right unit and you'll end up with weird results.
766 Here is what happens with a single transfer of size L on a link
767 (bw,lat) when nothing else happens.
770 0-----lat--------------------------------------------------t
771 |-----|**** real_bw =min(bw,SG_TCP_CTE_GAMMA/(2*lat)) *****|
774 In more complex situations, this min is the solution of a complex
775 max-min linear system. Have a look
776 <a href="http://lists.gforge.inria.fr/pipermail/simgrid-devel/2006-April/thread.html">here</a>
777 and read the two threads "Bug in SURF?" and "Surf bug not
778 fixed?". You'll have a few other examples of such computations. You
779 can also read "A Network Model for Simulation of Grid Application" by
780 Henri Casanova and Loris Marchal to have all the details. The fact
781 that the real_bw is smaller than bw is easy to understand. The fact
782 that real_bw is smaller than SG_TCP_CTE_GAMMA/(2*lat) is due to the
783 window-based congestion mechanism of TCP. With TCP, you can't exploit
784 your huge network capacity if you don't have a good round-trip-time
785 because of the acks...
787 Anyway, what you get is t=lat + L/min(bw,SG_TCP_CTE_GAMMA/(2*lat)).
789 * if I you set (bw,lat)=(100 000 000, 0.00001), you get t = 1.00001 (you fully
791 * if I you set (bw,lat)=(100 000 000, 0.0001), you get t = 1.0001 (you're on the
793 * if I you set (bw,lat)=(100 000 000, 0.001), you get t = 10.001 (ouch!)
795 This bound on the effective bandwidth of a flow is not the only thing
796 that may make your result be unexpected. For example, two flows
797 competing on a saturated link receive an amount of bandwidth inversely
798 proportional to their round trip time.
800 \subsection faq_bugrepport So I've found a bug in SimGrid. How to report it?
802 We do our best to make sure to hammer away any bugs of SimGrid, but this is
803 still an academic project so please be patient if/when you find bugs in it.
804 If you do, the best solution is to drop an email either on the simgrid-user
805 or the simgrid-devel mailing list and explain us about the issue. You can
806 also decide to open a formal bug report using the
807 <a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">relevant
808 interface</a>. You need to login on the server to get the ability to submit
811 We will do our best to solve any problem repported, but you need to help us
812 finding the issue. Just telling "it segfault" isn't enough. Telling "It
813 segfaults when running the attached simulator" doesn't really help either.
814 You may find the following article interesting to see how to repport
815 informative bug repports:
816 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid
817 specific at all, but it's full of good advices).
819 \author Da SimGrid team <simgrid-devel@lists.gforge.inria.fr>
823 ******************************************************************
824 * OLD CRUFT NOT USED ANYMORE *
825 ******************************************************************
828 subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
830 At the moment, we do not distribute Windows pre-compiled version of SimGrid
831 because the support for this platform is still experimental. We know that
832 some parts of the GRAS environment do not work, and we think that the others
833 environments (MSG and SD) have good chances to work, but we didn't test
834 ourselves. This section explains how we generate the SimGrid DLL so that you
835 can build it for yourself. First of all, you need to have a version more
836 recent than 3.1 (ie, a SVN version as time of writting).
838 In order to cross-compile the package to windows from linux, you need to
839 install mingw32 (minimalist gnu win32). On Debian, you can do so by
840 installing the packages mingw32 (compiler), mingw32-binutils (linker and
841 so), mingw32-runtime.
843 You can use the VPATH support of configure to compile at the same time for
844 linux and windows without dupplicating the source nor cleaning the tree
845 between each. Just run bootstrap (if you use the SVN) to run the autotools.
846 Then, create a linux and a win directories. Then, type:
847 \verbatim cd linux; ../configure --srcdir=.. <usual configure flags>; make; cd ..
848 cd win; ../configure --srcdir=.. --host=i586-mingw32msvc <flags>; make; cd ..
850 The trick to VPATH builds is to call configure from another directory,
851 passing it an extra --srcdir argument to tell it where all the sources are.
852 It will understand you want to use VPATH. Then, the trick to cross-compile
853 is simply to add a --host argument specifying the target you want to build
854 for. The i586-mingw32msvc string is what you have to pass to use the mingw32
855 environment as distributed in Debian.
857 After that, you can run all make targets from both directories, and test
858 easily that what you change for one arch does not break the other one.
860 It is possible that this VPATH build thing breaks from time to time in the
861 SVN since it's quite fragile, but it's granted to work in any released
862 version. If you experience problems, drop us a mail.
864 Another possible source of issue is that at the moment, building the
865 examples request to use the gras_stub_generator tool, which is a compiled
866 program, not a script. In cross-compilation, you need to cross-execute with
867 wine for example, which is not really pleasant. We are working on this, but
868 in the meanwhile, simply don't build the examples in cross-compilation
869 (<tt>cd src</tt> before running make).
871 Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be
872 usable. For example, if you want to test your build with wine, you should do
873 the following to put this library where wine looks for DLLs.
875 cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/
876 gunzip ~/.wine/c/windows/system/mingwm10.dll.gz
879 The DLL is built in src/.libs, and installed in the <i>prefix</i>/bin directory
880 when you run make install.
882 If you want to use it in a native project on windows, you need to use
883 simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file
884 under linux (listing the defined symbols), and convert it into a .lib file
885 under windows (specifying this in a way that windows compilers like). To
886 generate the def files, run (under linux):
887 \verbatim echo "LIBRARY libsimgrid-0.dll" > simgrid.def
888 echo EXPORTS >> simgrid.def
889 nm libsimgrid-0.dll | grep ' T _' | sed 's/.* T _//' >> simgrid.def
890 nm libsimgrid-0.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> simgrid.def
892 echo "LIBRARY mingwm10.dll" > mingwm10.def
893 echo EXPORTS >> mingwm10.def
894 nm mingwm10.dll | grep ' T _' | sed 's/.* T _//' >> mingwm10.def
895 nm mingwm10.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> mingwm10.def
898 To create the import .lib files, use the <tt>lib</tt> windows tool (from
899 MSVC) the following way to produce simgrid.lib and mingwm10.lib
900 \verbatim lib /def:simgrid.def
901 lib /def:mingwm10.def
904 If you happen to use Borland C Builder, the right command line is the
905 following (note that you don't need any file.def to get this working).
906 \verbatim implib simgrid.lib libsimgrid-0.dll
907 implib mingwm10.lib mingwm10.dll
910 Then, set the following parameters in Visual C++ 2005:
911 Linker -> Input -> Additional dependencies = simgrid.lib mingwm10.lib
913 Just in case you wonder how to generate a DLL from libtool in another
914 project, we added -no-undefined to any lib*_la_LDFLAGS variables so that
915 libtool accepts to generate a dynamic library under windows. Then, to make
916 it true, we pass any dependencies (such as -lws2 under windows or -lpthread
917 on need) on the linking line. Passing such deps is a good idea anyway so
918 that they get noted in the library itself, avoiding the users to know about
919 our dependencies and put them manually on their compilation line. Then we
920 added the AC_LIBTOOL_WIN32_DLL macro just before AC_PROG_LIBTOOL in the
921 configure.ac. It means that we exported any symbols which need to be.
922 Nowadays, functions get automatically exported, so we don't need to load our
923 header files with tons of __declspec(dllexport) cruft. We only need to do so
924 for data, but there is no public data in SimGrid so we are good.