/*! \page faq Frequently Asked Questions
-\htmlinclude FAQ.toc
+\htmlinclude .FAQ.doc.toc
\section faq_installation Installing the SimGrid library
make install
\endverbatim
-If at some point, something fails, you can report me this problem but,
-please, avoid sending a laconic mail like "There is a problem. Is it
-normal?". Send me the config.log file which is automatically
-generated by configure. Try to capture both the standard output and
-the error output of the <tt>make</tt> command. There is no way for me
-to help you if you do not give me a little bit of information.
+If at some point, something fails, check the section "\ref
+faq_compil_trouble". If it does not help, you can report this problem to the
+list but, please, avoid sending a laconic mail like "There is a problem. Is it
+okay?". Send the config.log file which is automatically generated by
+configure. Try to capture both the standard output and the error output of the
+<tt>make</tt> command with <tt>script</tt>. There is no way for us to help you
+without the relevant bits of information.
Now, the following directory should have been created :
version are available. Here is what you can find if you try a <tt>ls
/home/joe/lib</tt>:
-\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
+\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
\endverbatim
Thus, there is two ways to link your program with SimGrid:
As usual, you're welcome to participate.
-\section faq_questions How to ....? Is there a function in the API to simply ....?
+\section faq_MIA How to ....? Is there a function in the API to simply ....?
Here is the deal. The whole SimGrid project (MSG, SURF, GRAS, ...) is
meant to be kept as simple and generic as possible. We cannot add
people have asked about it and we have given hints on how to simply do
it with MSG. Feel free to contribute...
-\subsection faq_examples I want some more complex examples!
+\subsection faq_MIA_examples I want some more complex examples!
Many people have come to ask me a more complex example and each time,
they have realized afterward that the basics were in the previous three
us if something is not clear and once again feel free to participate!
:)
-\subsection faq_examples_MIA_taskdup Missing in action: Task duplication/replication
+\subsection faq_MIA_taskdup Missing in action: Task duplication/replication
There is no task duplication in MSG. When you create a task, you can
process it or send it somewhere else. As soon as a process has sent
You could use a dictionnary (#xbt_dict_t) of dynars (#xbt_dict_t). If
you still don't see how to do it, please come back to us...
-\subsection faq_examples_MIA_asynchronous I want to do asynchronous communications.
+\subsection faq_MIA_asynchronous I want to do asynchronous communications.
Up until now, there is no asynchronous communications in MSG. However,
you can create as many process as you want so you should be able to do
process only to handle communications may be problematic in term of
performance at some point). I'll add it in the distribution asap.
-\subsection faq_examples_MIA_thread_synchronization I need to synchronize my process
+\subsection faq_MIA_thread_synchronization I need to synchronize my processes
You obviously cannot use pthread_mutexes of pthread_conds. The best
thing would be to propose similar structures. Unfortunately, we
synchronization with fake communications (using MSG_task_get(),
MSG_task_put() and MSG_task_Iprobe()).
-\subsection faq_examples_MIA_host_load Where is the get_host_load function hidden in MSG?
+\subsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
There is no such thing because its semantic wouldn't be really
clear. Of course, it is something about the amount of host throughput,
case, please detail what you mean on the mailing list, and we will extend
this FAQ section to fit your taste if possible.
-\subsection faq_examples_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid ?
+\subsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid ?
No, there is no native support for batch schedulers and none is
planned because this is a very specific need (and doing it in a
and put his code in the contrib directory of our CVS so that other can
keep working on it. You may find inspinring ideas in it.
+\subsection faq_MIA_checkpointing I need a checkpointing thing
+
+Actually, it depends on whether you want to checkpoint the simulation, or to
+simulate checkpoints.
+
+The first one could help if your simulation is a long standing process you
+want to keep running even on hardware issues. It could also help to
+<i>rewind</i> the simulation by jumping sometimes on an old checkpoint to
+cancel recent calculations.\n
+Unfortunately, such thing will probably never exist in SG. One would have to
+duplicate all data structures because doing a rewind at the simulator level
+is very very hard (not talking about the malloc free operations that might
+have been done in between). Instead, you may be interested in the Libckpt
+library (http://www.cs.utk.edu/~plank/plank/www/libckpt.html). This is the
+checkpointing solution used in the condor project, for example. It makes it
+easy to create checkpoints (at the OS level, creating something like core
+files), and rerunning them on need.
+
+If you want to simulate checkpoints instead, it means that you want the
+state of an executing task (in particular, the progress made towards
+completion) to be saved somewhere. So if a host (and the task executing on
+it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted
+from the last checkpoint.\n
+
+Actually, such a thing does not exists in SimGrid either, but it's just
+because we don't think it is fundamental and it may be done in the user code
+at relatively low cost. You could for example use a watcher that
+periodically get the remaining amount of things to do (using
+MSG_task_get_remaining_computation()), or fragment the task in smaller
+subtasks.
+
\section faq_SG Where has SG disappeared?!?
OK, it's time to explain what's happening to the SimGrid project. Let's
to gforge so people that are interested by helping on this part will
have the possibility to do it.
-\subsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs without the SG module?
+\subsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs.
Distributed is somehow "contagious". If you start making distributed
decisions, there is no way to handle DAGs directly anymore (unless I am
missing something). You have to encode your DAGs in term of communicating
process to make the whole scheduling process distributed. Believe me, it is
worth the effort since you'll then be able to try your algorithms in a very
-wide variety of conditions.
+wide variety of conditions. Here is an example of how you could do that.
+Assume T1 has to be done before T2.
+\verbatim
+ int your_agent(int argc, char *argv[] {
+ ...
+ T1 = MSG_task_create(...);
+ T2 = MSG_task_create(...);
+ ...
+ while(1) {
+ ...
+ if(cond) MSG_task_execute(T1);
+ ...
+ if((MSG_task_get_remaining_computation(T1)=0.0) && (you_re_in_a_good_mood))
+ MSG_task_execute(T2)
+ else {
+ /* do something else */
+ }
+ }
+ }
+\endverbatim
+
If you decide that the distributed part is not that much important and that
DAG is really the level of abstraction you want to work with (but it
prevents you from having "realistic" platform modeling), then you should
Note however that SURF will be slower than the old SG to handle traces with
a lots of variations (there is no trace integration anymore).
+\subsection faq_SG_future Will SG come back in the maintained branch one day?
+
+Sure. In fact, we already have thought about a new and cleaner API:
+\verbatim
+void* SG_link_get_data(SG_link_t link);
+void SG_link_set_data(SG_link_t link, void *data);
+const char* SG_link_get_name(SG_link_t link);
+double SG_link_get_capacity(SG_link_t link);
+double SG_link_get_current_bandwidth(SG_link_t link);
+double SG_link_get_current_latency(SG_link_t link);
+
+SG_workstation_t SG_workstation_get_by_name(const char *name);
+SG_workstation_t* SG_workstation_get_list(void);
+int SG_workstation_get_number(void);
+void SG_workstation_set_data(SG_workstation_t workstation, void *data);
+void * SG_workstation_get_data(SG_workstation_t workstation);
+const char* SG_workstation_get_name(SG_workstation_t workstation);
+SG_link_t* SG_workstation_route_get_list(SG_workstation_t src, SG_workstation_t dst);
+int SG_workstation_route_get_size(SG_workstation_t src, SG_workstation_t dst);
+double SG_workstation_get_power(SG_workstation_t workstation);
+double SG_workstation_get_available_power(SG_workstation_t workstation);
+
+SG_task_t SG_task_create(const char *name, void *data, double amount);
+int SG_task_schedule(SG_task_t task, int workstation_nb,
+ SG_workstation_t **workstation_list, double *computation_amount,
+ double *communication_amount, double rate);
+
+void* SG_task_get_data(SG_task_t task);
+void SG_task_set_data(SG_task_t task, void *data);
+const char* SG_task_get_name(SG_task_t task);
+double SG_task_get_amount(SG_task_t task);
+double SG_task_get_remaining_amount(SG_task_t task);
+void SG_task_dependency_add(const char *name, void *data, SG_task_t src, SG_task_t dst);
+void SG_task_dependency_remove(SG_task_t src, SG_task_t dst);
+e_SG_task_state_t SG_task_state_get(SG_task_t task); /* e_SG_task_state_t can be either SG_SCHEDULED, SG_RUNNING, SG_DONE, or SG_FAILED */
+void SG_task_watch(SG_task_t task, e_SG_task_state_t state); /* SG_simulate will stop as soon as the state of this task is the one given in argument.
+ Watch-point is then automatically removed */
+void SG_task_unwatch(SG_task_t task, e_SG_task_state_t state);
+
+void SG_task_unschedule(SG_task_t task); /* change state and rerun.. */
+
+SG_task_t *SG_simulate(double how_long); /* returns a NULL-terminated array of SG_task_t whose state has changed */
+\endverbatim
+
+We're just looking for somebody to implement it... :)
+
\section faq_dynamic Dynamic resources and platform building
\subsection faq_platform Building a realistic platform
bandwidth_file and latency_file do not express fraction of available
power but are expressed directly in Mb/s and seconds.
-\subsection faq_flexml_bypassing How could I have some C functions do what the platform and deployment files do?
+\subsection faq_flexml_bypassing How can I have some C functions do what the platform file does?
So you want to bypass the XML files parser, uh? Maybe doin some parameter
sweep experiments on your simulations or so? This is possible, but it's not
\section faq_troubleshooting Troubleshooting
+\subsection faq_compil_trouble ./configure fails!
+
+We now only one reason for the configure to fail:
+
+ - <b>You are using a borken build environment</b>\n
+ If symptom is that configure complains about gcc not being able to build
+ executables, you are probably missing the libc6-dev package. Damn Ubuntu.
+
+If you experience other kind of issue, please get in touch with us. We are
+always interested in improving our portability to new systems.
+
+\subsection faq_distcheck_fails Dude! "make check" fails on my machine!
+
+Don't assume we never run this target, because we do. Really. Promise!
+
+There is several reasons which may cause the make check to fail on your
+machine:
+
+ - <b>You are using a borken compiler</b>.\n
+ The symptom may be that the "make check" fails within testsuite/gras
+ directory.\n
+ For example, the breezy release of Ubuntu comes with a prerelease of the
+ 4.0 gcc compiler. This version happens to be completely unusable, and you
+ should install a gcc-3.4 compiler and change the /usr/bin/gcc link to let
+ it point on /usr/bin/gcc-3.4.
+ - <b>You are using a borken libc (probably concerning the contextes)</b>.\n
+ The symptom is that the "make check" fails within the examples/msg directory.\n
+ By default, SimGrid uses something called ucontexts. This is part of the
+ libc, but it's quite undertested. For example, some (old) versions of the
+ glibc on alpha do not implement these functions, but provide the stubs
+ (which return ENOSYS: not implemented). It fools our detection mecanism
+ and leads to segfaults.\n
+ On some x86_64, the pointer to function is stored into a integer, but int
+ are 32bits only on this arch while pointers are 64bits. Our detection
+ mecanism also fails to detect the problem, which leads to segfaults.\n
+ In both cases, there is not much we can do to fix the bug. We are working
+ on a workaround for x86_64 machines, but in the meanwhile, you can
+ compile with --with-context=pthread to avoid ucontext completely. You'll
+ be a bit more limitated in the number of simulated processes you can start
+ concurently, but 5000 processes is still enough for most purposes, isn't
+ it?\n
+ This limitation is the reason why we insist on using this piece of ...
+ software even if it's so troublesome.
+ - <b>There is a bug in SimGrid we aren't aware of</b>.\n
+ If none of the above apply, please drop us a mail on the mailing list so
+ that we can check it out.
+
\subsection faq_context_1000 I want thousands of simulated processes
SimGrid can use either pthreads library or the UNIX98 contextes. On most
adapted version is picked up.
We experienced some issues with contextes on some rare systems (solaris 8
-and lower comes to mind). The main problem is that the configure script
-detect the contextes as being functional when it's not true. If you happen
-to use such a system, switch manually to the pthread version, and provide us
-with a good patch for the configure script so that it is done automatically ;)
+and lower or old alpha linuxes comes to mind). The main problem is that the
+configure script detect the contextes as being functional when it's not
+true. If you happen to use such a system, switch manually to the pthread
+version, and provide us with a good patch for the configure script so that
+it is done automatically ;)
\subsection faq_context_10000 I want hundred thousands of simulated processes
low, you'll get a segfault. The token ring example, which is quite simple,
runs with 40kb stacks.
+\subsection faq_longjmp longjmp madness
+
+This is when valgrind starts complaining about longjmp things, just like:
+
+\verbatim ==21434== Conditional jump or move depends on uninitialised value(s)
+==21434== at 0x420DBE5: longjmp (longjmp.c:33)
+==21434==
+==21434== Use of uninitialised value of size 4
+==21434== at 0x420DC3A: __longjmp (__longjmp.S:48)
+\endverbatim
+
+or even when it reports scary things like:
+
+\verbatim ==24023== Warning: client switching stacks? SP change: 0xBE3FF618 --> 0xBE7FF710
+x86->IR: unhandled instruction bytes: 0xF4 0xC7 0x83 0xD0
+==24023== to suppress, use: --max-stackframe=4194552 or greater
+==24023== Your program just tried to execute an instruction that Valgrind
+==24023== did not recognise. There are two possible reasons for this.
+==24023== 1. Your program has a bug and erroneously jumped to a non-code
+==24023== location. If you are running Memcheck and you just saw a
+==24023== warning about a bad jump, it's probably your program's fault.
+==24023== 2. The instruction is legitimate but Valgrind doesn't handle it,
+==24023== i.e. it's Valgrind's fault. If you think this is the case or
+==24023== you are not sure, please let us know.
+==24023== Either way, Valgrind will now raise a SIGILL signal which will
+==24023== probably kill your program.
+==24023==
+==24023== Process terminating with default action of signal 4 (SIGILL)
+==24023== Illegal opcode at address 0x420D234
+==24023== at 0x420D234: abort (abort.c:124)
+\endverbatim
+
+This is the sign that you didn't used the exception mecanism well. Most
+probably, you have a <tt>return;</tt> somewhere within a <tt>TRY{}</tt>
+block. This is <b>evil</b>, and you must not do this. Did you read the section
+about \ref XBT_ex??
+
\subsection faq_flexml_limit I get the message "surf_parse_lex: Assertion `next<limit' failed."
This is because your platform file is too big for the parser.
Unfortunately, we cannot debug every code written in SimGrid. We
furthermore believe that the framework provides ways enough
information to debug such informations yourself. If the textual output
-is not enough, Make sure to check the \ref faq_paje FAQ entry to see
+is not enough, Make sure to check the \ref faq_visualization FAQ entry to see
how to get a graphical one.
Now, if you come up with a really simple example that deadlocks and
on your side... We have plenty of FAQ entries to redact and new
features to implement for the impenitents! ;)
-\author Arnaud Legrand (arnaud.legran::imag.fr)
+\author Arnaud Legrand (arnaud.legrand::imag.fr)
\author Martin Quinson (martin.quinson::loria.fr)
