X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/201c5b2ae5ceba890c5e9ac5060824ddd5d5ba8b..b401ba10cae8b375d11bee6d24b116936a91acb5:/doc/FAQ.doc
diff --git a/doc/FAQ.doc b/doc/FAQ.doc
index 9acea6505c..de38773ac7 100644
--- a/doc/FAQ.doc
+++ b/doc/FAQ.doc
@@ -1,6 +1,109 @@
/*! \page faq Frequently Asked Questions
-\htmlinclude FAQ.toc
+\htmlinclude .FAQ.doc.toc
+
+\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
+
+You are at the right place... Having a look to these
+slides
+(or to these
+"obsolete" slides)
+may give you some insights on what SimGrid can help you to do and what
+are its limitations. Then you definitely should read the \ref
+MSG_examples. There is also a mailing list: .
+
+\subsection faq_interfaces What is the difference between MSG, SimDag, and GRAS? Do they serve the same purpose?
+
+It depend on how you define "purpose", I guess ;)
+
+They all allow you to build a prototype of application which you can run
+within the simulator afterward. They all share the same simulation kernel,
+which is the core of the SimGrid project. They differ by the way you express
+your application.
+
+With SimDag, you express your code as a collection of interdependent
+parallel tasks. So, in this model, applications can be seen as a DAG of
+tasks.
+
+With both GRAS and MSG, your application is seen as a set of communicating
+processes, exchanging data by the way of messages and performing computation
+on their own.
+
+The difference between both is that MSG is somehow easier to use, but GRAS
+is not limitated to the simulator. Once you're done writing your GRAS code,
+you can run your code both in the simulator or on a real platform. For this,
+there is two implementations of the GRAS interface, one for simulation, one
+for real execution. So, you just have to relink your code to chose one of
+both world.
+
+\subsection faq_generic First steps with SimGrid
+
+If you decide to go for the MSG interface, please read carefully the
+\ref MSG_examples. You'll find in \ref MSG_ex_master_slave a very
+simple consisting of a master (that owns a bunch of tasks and
+distributes them) , some slaves (that process tasks whenever they
+receive one) and some forwarder agents (that simply pass the tasks
+they receive to some slaves).
+
+If you decide to go for the GRAS interface, you should definitively
+read the \ref GRAS_tut. The first section constitutes an introduction
+to the tool and presents the model we use. The second section
+constitutes a complete step-by-step tutorial building a distributed
+application from the begining and exemplifying most of the GRAS
+features in the process. The last section groups some HOWTOS
+highlighting a given feature of the framework in a more concise way.
+
+If you decide to go for another interface, I'm afraid your only sources
+of information will be the source code and the mailing lists...
+
+\subsection faq_visualization Visualizing and analyzing the results
+
+It is sometime convenient to "see" how the agents are behaving. If you
+like colors, you can use tools/MSG_visualization/colorize.pl
+as a filter to your MSG outputs. It works directly with INFO. Beware,
+INFO() prints on stderr. Do not forget to redirect if you want to
+filter (e.g. with bash):
+\verbatim
+./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
+\endverbatim
+
+We also have a more graphical output. Have a look at MSG_paje_output(). It
+generates an input to Paje.
+
+\htmlonly
+ 
+\endhtmlonly
+
+
+Vizualization with Paje can be seen as a kind of postmortem
+analysis. However, as soon as you start playing with big simulations,
+you'll realize that processing such output is kind of tricky. There is
+so much generic informations that it is hard to find the information
+you are looking for.
+
+As a matter of fact, loging really depends on simulations (e.g. what
+kind of events is important...). That is why we do not propose a big
+dump of your whole simulation (it would slow everything down) but give
+you neat tools to structure you logs. Have a look at \ref XBT_log. In
+fact, rather than a post-mortem analysis, you may want to do it on the
+fly. The process you are running can do whatever you want. Have you
+thought about adding a global structure where you directly compute the
+informations that are really important rather than writing everything
+down and then processing huge files?
+
+\subsection faq_C Argh! Do I really have to code in C?
+
+Up until now, there is no binding for other languages. If you use C++,
+you should be able to use the SimGrid library as a standard C library
+and everything should work fine (simply link against this
+library; recompiling SimGrid with a C++ compiler won't work and it
+wouldn't help if you could).
+
+In fact, we are currently working on Java bindings of MSG to allow
+all the undergrad students of the world to use this tool. This is a
+little more tricky than I would have expected, but the work is moving
+fast forward [2006/05/13]. More languages are evaluated, but for now,
+we do not feel a real demand for any other language. Please speak up!
\section faq_installation Installing the SimGrid library
@@ -11,25 +114,28 @@ not familiar with compiling C files under UNIX. If you follow these
instructions and still have some troubles, drop an e-mail to
.
-\subsection faq_compiling Compiling SimGrid
+\subsection faq_compiling Compiling SimGrid from an archive
+First of all, you need to download the latest version of SimGrid from
+here.
Suppose you have uncompressed SimGrid in some temporary location of
-your home directory (say /home/joe/tmp/simgrid-2.18.2 ). The
+your home directory (say /home/joe/tmp/simgrid-3.0.1 ). The
simplest way to use SimGrid is to install it in your home
directory. Change your directory to
-/home/joe/tmp/simgrid-2.18.2 and type
+/home/joe/tmp/simgrid-3.0.1 and type
\verbatim./configure --prefix=$HOME
make
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 make 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_trouble_compil". 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
+make command with script. There is no way for us to help you
+without the relevant bits of information.
Now, the following directory should have been created :
@@ -41,7 +147,7 @@ SimGrid is not a binary, it is a library. Both a static and a dynamic
version are available. Here is what you can find if you try a ls
/home/joe/lib:
-\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:
@@ -62,7 +168,62 @@ Thus, there is two ways to link your program with SimGrid:
\verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
\endverbatim
-\subsection faq_setting Setting up your own code
+
+\subsection faq_compiling_cvs Compiling SimGrid from the CVS
+
+The project development takes place in the cvs, where all changes are
+commited when they happen. Then every once in a while, we make sure that the
+code quality meets our standard and release an archive from the code in the
+CVS. We afterward go back to the development in the CVS. So, if you need a
+recently added feature and can afford some little problem with the stability
+of the lastest features, you may want to use the CVS version instead of a
+released one.
+
+For that, you first need to get the "simgrid" module from
+here.
+
+You won't find any configure and a few other things
+(Makefile.in's, documentation, ...) will be missing as well. The
+reason for that is that all these files have to be regenerated using the
+latest versions of autoconf, libtool, automake
+(>1.9) and doxygen (>1.4). To generate the configure and
+the Makefile.in's, you just have to launch the bootstrap
+command that resides in the top of the source tree. Then just follow the
+instructions of Section \ref faq_compiling.
+
+We insist on the fact that you really need the latest versions of
+autoconf, automake and libtool. Doing this step on exotic architectures/systems
+(i.e. anything different from a recent linux distribution) may be
+... uncertain. If you need to compile the CVS version on a machine where all these
+dependencies are not met, the easiest is to do make dist in the CVS
+dir of another machine where all dependencies are met. It will create an
+archive you may deploy on other sites just as a regular stable release.
+
+In summary, the following commands will checkout the CVS, regenerate the
+configure script and friends, configure SimGrid and build it.
+
+\verbatim cvs -d :pserver:anonymous@scm.gforge.inria.fr:/cvsroot/simgrid login
+cvs -d :pserver:anonymous@scm.gforge.inria.fr:/cvsroot/simgrid checkout simgrid
+cd simgrid
+./bootstrap
+./configure --enable-maintainer-mode --prefix=
+make \endverbatim
+
+Then, if you want to install SimGrid on the current box, just do:
+\verbatim make install \endverbatim
+
+If you want to build an snapshot of the CVS to deploy it on another box (for
+example because the other machine don't have the autotools), do:
+\verbatim make dist \endverbatim
+
+Moreover, you should never call the autotools manually since you must run
+them in a specific order with specific arguments. Most of the times, the
+makefiles will automatically call the tools for you. When it's not possible
+(such as the first time you checkout the CVS), use the ./bootstrap command
+to call them explicitely.
+
+
+\subsection faq_setting_MSG Setting up your own MSG code
Do not build your simulator by modifying the SimGrid examples. Go
outside the SimGrid source tree and create your own working directory
@@ -89,9 +250,9 @@ feel free to organize it as you want).
MSG_launch_application()) and the call to
MSG_main()).
-To compile such a program, I suggest to use the following Makefile. It
-is a generic Makefile that I generally use with my students when I
-teach the C language.
+To compile such a program, we suggest to use the following
+Makefile. It is a generic Makefile that we have used many times with
+our students when we teach the C language.
\verbatim
all: masterslave
@@ -141,23 +302,136 @@ in a terminal : info make and read the introduction. The
previous example should be enough for a first try but you may want to
perform some more complex compilations...
-\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start ?
+\subsection faq_setting_GRAS Setting up your own GRAS code
+
+If you use the GRAS interface instead of the MSG one, then previous section
+is not the better source of information. Instead, you should check the GRAS
+tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
+
+\subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
+
+At the moment, we do not distribute Windows pre-compiled version of SimGrid
+because the support for this platform is still experimental. We know that
+some parts of the GRAS environment do not work, and we think that the others
+environments (MSG and SD) have good chances to work, but we didn't test
+ourselves. This section explains how we generate the SimGrid DLL so that you
+can build it for yourself. First of all, you need to have a version more
+recent than 3.1 (ie, a CVS version as time of writting).
+
+In order to cross-compile the package to windows from linux, you need to
+install mingw32 (minimalist gnu win32). On Debian, you can do so by
+installing the packages mingw32 (compiler), mingw32-binutils (linker and
+so), mingw32-runtime.
+
+You can use the VPATH support of configure to compile at the same time for
+linux and windows without dupplicating the source nor cleaning the tree
+between each. Just run bootstrap (if you use the CVS) to run the autotools.
+Then, create a linux and a win directories. Then, type:
+\verbatim cd linux; ../configure --srcdir=.. ; make; cd ..
+cd win; ../configure --srcdir=.. --host=i586-mingw32msvc ; make; cd ..
+\endverbatim
+The trick to VPATH builds is to call configure from another directory,
+passing it an extra --srcdir argument to tell it where all the sources are.
+It will understand you want to use VPATH. Then, the trick to cross-compile
+is simply to add a --host argument specifying the target you want to build
+for. The i586-mingw32msvc string is what you have to pass to use the mingw32
+environment as distributed in Debian.
+
+After that, you can run all make targets from both directories, and test
+easily that what you change for one arch does not break the other one.
+
+It is possible that this VPATH build thing breaks from time to time in the
+CVS since it's quite fragile, but it's granted to work in any released
+version. If you experience problems, drop us a mail.
+
+Another possible source of issue is that at the moment, building the
+examples request to use the gras_stub_generator tool, which is a compiled
+program, not a script. In cross-compilation, you need to cross-execute with
+wine for example, which is not really pleasant. We are working on this, but
+in the meanwhile, simply don't build the examples in cross-compilation
+(cd src before running make).
+
+Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be
+usable. For example, if you want to test your build with wine, you should do
+the following to put this library where wine looks for DLLs.
+\verbatim
+cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/
+gunzip ~/.wine/c/windows/system/mingwm10.dll.gz
+\endverbatim
-You are at the right place... Having a look to these
-slides
-may give you some insights on what SimGrid can help you to do and what
-are its limitations. Then you definitely should read the \ref
-MSG_examples. There is also a mailing list: .
+The DLL is builded in src/.libs, and installed in the prefix/bin directory
+when you run make install.
+
+If you want to use it in a native project on windows, you need to use
+simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file
+under linux (listing the defined symbols), and convert it into a .lib file
+under windows (specifying this in a way that windows compilers like). To
+generate the def files, run (under linux):
+\verbatim echo "LIBRARY libsimgrid-0.dll" > simgrid.def
+echo EXPORTS >> simgrid.def
+nm libsimgrid-0.dll | grep ' T _' | sed 's/.* T _//' >> simgrid.def
+nm libsimgrid-0.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> simgrid.def
+
+echo "LIBRARY mingwm10.dll" > mingwm10.def
+echo EXPORTS >> mingwm10.def
+nm mingwm10.dll | grep ' T _' | sed 's/.* T _//' >> mingwm10.def
+nm mingwm10.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> mingwm10.def
+\endverbatim
-\subsection faq_generic Building a generic simulator
+To create the import .lib files, use the lib windows tool (from
+MSVC) the following way to produce simgrid.lib and mingwm10.lib
+\verbatim lib /def:simgrid.def
+lib /def:mingwm10.def
+\endverbatim
-Please read carefully the \ref MSG_examples. You'll find in \ref
-MSG_ex_master_slave a very simple consisting of a master (that owns a bunch of
-tasks and distributes them) , some slaves (that process tasks whenever
-they receive one) and some forwarder agents (that simply pass the
-tasks they receive to some slaves).
+If you happen to use Borland C Builder, the right command line is the
+following (note that you don't need any file.def to get this working).
+\verbatim implib simgrid.lib libsimgrid-0.dll
+implib mingwm10.lib mingwm10.dll
+\endverbatim
-\subsection faq_examples I want some more complex examples !
+Then, set the following parameters in Visual C++ 2005:
+Linker -> Input -> Additional dependencies = simgrid.lib mingwm10.lib
+
+Just in case you wonder how to generate a DLL from libtool in another
+project, we added -no-undefined to any lib*_la_LDFLAGS variables so that
+libtool accepts to generate a dynamic library under windows. Then, to make
+it true, we pass any dependencies (such as -lws2 under windows or -lpthread
+on need) on the linking line. Passing such deps is a good idea anyway so
+that they get noted in the library itself, avoiding the users to know about
+our dependencies and put them manually on their compilation line. Then we
+added the AC_LIBTOOL_WIN32_DLL macro just before AC_PROG_LIBTOOL in the
+configure.ac. It means that we exported any symbols which need to be.
+Nowadays, functions get automatically exported, so we don't need to load our
+header files with tons of __declspec(dllexport) cruft. We only need to do so
+for data, but there is no public data in SimGrid so we are good.
+
+\section faq_howto Feature related questions
+
+\subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
+
+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
+functions for everybody's need when these functions can easily be
+built from the ones already in the API. Most of the time, it is
+possible and when it was not possible we always have upgraded the API
+accordingly. When somebody asks us a question like "How to do that?
+Is there a function in the API to simply do this?", we're always glad
+to answer and help. However if we don't need this code for our own
+need, there is no chance we're going to write it... it's your job! :)
+The counterpart to our answers is that once you come up with a neat
+implementation of this feature (task duplication, RPC, thread
+synchronization, ...), you should send it to us and we will be glad to
+add it to the distribution. Thus, other people will take advantage of
+it (and we don't have to answer this question again and again ;).
+
+You'll find in this section a few "Missing In Action" features. Many
+people have asked about it and we have given hints on how to simply do
+it with MSG. Feel free to contribute...
+
+\subsection faq_MIA_MSG MSG features
+
+\subsubsection faq_MIA_examples I want some more complex MSG 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
@@ -171,105 +445,150 @@ receptions), or even MSG_process_create() (to design asynchronous
communications or computations). But the examples are sufficient to
start.
-I know I should add some more examples, but not some more complex
-ones... I should add some examples that illustrate some other
+We know. We should add some more examples, but not really some more
+complex ones... We should add some examples that illustrate some other
functionalities (like how to simply encode asynchronous
communications, RPC, process migrations, thread synchronization, ...)
-and I will do it when I will have a little bit more time. I have tried
-to document the examples so that they are understandable. I know it is
-not really satisfying but it is the best I have managed to do yet.
+and we will do it when we will have a little bit more time. We have
+tried to document the examples so that they are understandable. Tell
+us if something is not clear and once again feel free to participate!
+:)
+
+\subsubsection faq_MIA_taskdup Missing in action: MSG 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
+this task, he doesn't have this task anymore. It's gone. The receiver
+process has got the task. However, you could decide upon receiving to
+create a "copy" of a task but you have to handle by yourself the
+semantic associated to this "duplication".
+
+As we already told, we prefer keeping the API as simple as
+possible. This kind of feature is rather easy to implement by users
+and the semantic you associate really depends on people. Having a
+*generic* task duplication mechanism is not that trivial (in
+particular because of the data field). That is why I would recommand
+that you write it by yourself even if I can give you advice on how to
+do it.
+
+You have the following functions to get informations about a task:
+MSG_task_get_name(), MSG_task_get_compute_duration(),
+MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
+and MSG_task_get_data().
+
+You could use a dictionnary (#xbt_dict_t) of dynars (#xbt_dynar_t). If
+you still don't see how to do it, please come back to us...
+
+\subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
+
+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
+whatever you want... I've written a queue module to help implementing
+some asynchronous communications at low cost (creating thousands of
+process only to handle communications may be problematic in term of
+performance at some point). I'll add it in the distribution asap.
+
+\subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
+
+You obviously cannot use pthread_mutexes of pthread_conds. The best
+thing would be to propose similar structures. Unfortunately, we
+haven't found time to do it yet. However you can try to play with
+MSG_process_suspend() and MSG_process_resume(). You can even do some
+synchronization with fake communications (using MSG_task_get(),
+MSG_task_put() and MSG_task_Iprobe()).
+
+\subsubsection 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,
+but there is as many definition of "host load" as people asking for
+this function. First, you have to remember that resource availability
+may vary over time, which make any load notion harder to define.
-\subsection faq_platform Building a realistic platform
+It may be instantaneous value or an average one. Moreover it may be only the
+power of the computer, or may take the background load into account, or may
+even take the currently running tasks into account. In some SURF models,
+communications have an influence on computational power. Should it be taken
+into account too?
-I can speak more than an hour on this subject and I still do not have
-the right answer, just some ideas. You can read the following
-slides.
-It may give you some hints. You can also have a look at the
-tools/platform_generation/ directory. There is a perl-script
-I use to annotate a Tiers generated platform (may not be up-to-date
-though).
+First of all, it's near to impossible to predict the load beforehands in the
+simulator since it depends on too much parameters (background load
+variation, bandwidth sharing algorithmic complexity) some of them even being
+not known beforehands (other task starting at the same time). So, getting
+this information is really hard (just like in real life). It's not just that
+we want MSG to be as painful as real life. But as it is in some way
+realistic, we face some of the same problems as we would face in real life.
+
+How would you do it for real? The most common option is to use something
+like NWS that performs active probes. The best solution is probably to do
+the same within MSG, as in next code snippet. It is very close from what you
+would have to do out of the simulator, and thus gives you information that
+you could also get in real settings to not hinder the realism of your
+simulation.
-\subsection faq_visualization Visualizing the schedule
+\verbatim
+double get_host_load() {
+ m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
+ double date = MSG_get_clock();
-It is sometime convenient to "see" how the agents are behaving. If you
-like colors, you can use tools/MSG_visualization/colorize.pl
-as a filter to your MSG outputs. It works directly with INFO. Beware,
-INFO() prints on stderr. Do not forget to redirect if you want to
-filter (e.g. with bash):
-\verbatim
-./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
+ MSG_task_execute(task);
+ date = MSG_get_clock() - date;
+ MSG_task_destroy(task);
+ return (0.001/date);
+}
\endverbatim
-We also have a more graphical output. Have a look at MSG_paje_output(). It
-generates an input to Paje.
-
-\htmlonly
-
-\endhtmlonly
-
-
-\subsection faq_context_1000 I want thousands of simulated processes
-
-SimGrid can use either pthreads library or the UNIX98 contextes. On most
-systems, the number of pthreads is limited and then your simulation may be
-limited for a stupid reason. This is especially true with the current linux
-pthreads, and I cannot get more than 2000 simulated processes with pthreads
-on my box. The UNIX98 contextes allow me to raise the limit to 25,000
-simulated processes on my laptop.
-
-The --with-context option of the ./configure script allows
-you to choose between UNIX98 contextes (--with-context=ucontext)
-and the pthread version ( (--with-context=pthread). The default
-value is ucontext when the script detect a working UNIX98 context
-implementation. On Windows boxes, the provided value is discarded and an
-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 ;)
-
-\subsection faq_context_10000 I want hundred thousands of simulated processes
-
-As explained above, SimGrid can use UNIX98 contextes to represent and handle
-the simulated processes. Thanks to this, the main limitation to the number
-of simulated processes becomes the available memory.
-
-Here are some tricks I had to use in order to run a token ring between
-25,000 processes on my laptop (1Gb memory, 1.5Gb swap).
-
- - First of all, make sure your code runs for a few hundreds processes
- before trying to push the limit. Make sure it's valgrind-clean, ie that
- valgrind does not report neither memory error nor memory leaks. Indeed,
- numerous simulated processes result in *fat* simulation hindering debugging.
+Of course, it may not match your personal definition of "host load". In this
+case, please detail what you mean on the mailing list, and we will extend
+this FAQ section to fit your taste if possible.
- - It was really boring to write 25,000 entries in the deployment file, so I wrote
- a little script examples/gras/tokenS/make_deployment.pl, which you may
- want to adapt to your case.
+\subsubsection faq_MIA_communication_time How can I get the *real* communication time?
- - The deployment file became quite big, so I had to do what is in the FAQ
- entry \ref faq_flexml_limit
+Communications are synchronous and thus if you simply get the time
+before and after a communication, you'll only get the transmission
+time and the time spent to really communicate (it will also take into
+account the time spent waiting for the other party to be
+ready). However, getting the *real* communication time is not really
+hard either. The following solution is a good starting point.
- - Each UNIX98 context has its own stack entry. As debugging this is quite
- hairly, the default value is a bit overestimated so that user don't get
- into trouble about this. You want to tune this size to increse the number
- of processes. This is the STACK_SIZE define in
- src/xbt/context_private.h, which is 128kb by default.
- Reduce this as much as you can, but be warned that if this value is too
- low, you'll get a segfault. The token ring example, which is quite simple,
- runs with 40kb stacks.
+\verbatim
+int sender()
+{
+ m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size,
+ calloc(1,sizeof(double)));
+ *((double*) task->data) = MSG_get_clock();
+ MSG_task_put(task, slaves[i % slaves_count], PORT_22);
+ INFO0("Send completed");
+ return 0;
+}
+int receiver()
+{
+ m_task_t task = NULL;
+ double time1,time2;
+
+ time1 = MSG_get_clock();
+ a = MSG_task_get(&(task), PORT_22);
+ time2 = MSG_get_clock();
+ if(time1<*((double *)task->data))
+ time1 = *((double *) task->data);
+ INFO1("Communication time : \"%f\" ", time2-time1);
+ free(task->data);
+ MSG_task_destroy(task);
+ return 0;
+}
+\endverbatim
+\subsection faq_MIA_SimDag SimDag related questions
-\section faq_SG Where has SG disappeared ?!?
+\subsubsection faq_SG Where has SG disappeared?
OK, it's time to explain what's happening to the SimGrid project. Let's
start with a little bit of history.
* Historically, SimGrid was a low-level toolkit for scheduling with
-classical models such as DAGs. That was SimGrid v.1.* aka SG, written by
-Henri Casanova. I had been using it in its earliest versions during an
-internship at UCSD.
+classical models such as DAGs. That was SimGrid v.1.* aka SG, written
+by Henri Casanova. I (Arnaud) had been using it in its earliest
+versions during an internship at UCSD.
Then we have realized that encoding distributed algorithm in SG was a
real pain.
@@ -327,8 +646,9 @@ speed provided by SURF.
Those two things are working, but we want to make everything as clean as
possible before releasing SimGrid v.3.
-So what about those nice DAGs we used to have in SimGrid v.1. ? They're not
-anymore in SimGrid v.3. Let me recall you the way SimGrid 3 is organized:
+So what about those nice DAGs we used to have in SimGrid v.1.? They're
+not anymore in SimGrid v.3. At least not in their original form... Let
+me recall you the way SimGrid 3 is organized:
\verbatim
________________
@@ -342,15 +662,17 @@ ________________
----------------
\endverbatim
-XBT is our tool box and now, you should have an idea of what the other ones
-are. As you can see, the primitive SG is not here anymore. However it could
-still be brought back if people really need it. Here is how it would fit.
+XBT is our tool box and now, you should have an idea of what the other
+ones are. As you can see, the primitive SG is not here
+anymore. However we have written a brand new and cleaner API for this
+purpose: \ref SD_API. It is built directly on top of SURF and provides
+an API rather close to the old SG:
\verbatim
______________________
| User code |
|____________________|
-| | MSG | GRAS | SG |
+| | MSG | GRAS | SD |
| -------------------|
| | SURF |
| -------------------|
@@ -358,34 +680,153 @@ ______________________
----------------------
\endverbatim
-Re-implementing SG on top of SURF is really straightforward (it only
-requires a little bit of time that I really don't have right now)
-since the only thing that lacks to SURF is the DAG part. But adding it
-to SURF would slow it down and therefore slow MSG and GRAS which is
-not a good thing. However it is really not on the top of our TODO
-list because we have to work on GRAS, and its MPI counterpart, and a
-parallel task model, and ... Anyway, we finally have migrated our CVS
-to gforge so people that are interested by helping on this part will
-have the possibility to do it.
+The nice thing is that, as it is writen on top of SURF, it seamlessly
+support DAG of parallel tasks as well as complex communications
+patterns. Some old codes using SG are currently under rewrite using
+\ref SD_API to check that all needful functions are provided.
-\subsection faq_SG_DAG But I wanted to implement a distributed dynamic scheduler of DAGs... How can I do that it SG is not available anymore in the next versions ?
+\subsubsection 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.
+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. 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
-keep using the 2.18.5 versions until somebody has ported SG on top of SURF.
-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).
-
+DAG is really the level of abstraction you want to work with, then you should
+give a try to \ref SD_API.
+
+\subsection faq_MIA_generic Generic features
+
+\subsubsection faq_more_processes Increasing the amount of simulated processes
+
+Here are a few tricks you can apply if you want to increase the amount
+of processes in your simulations.
+
+ - A few thousands of simulated processes (soft tricks)\n
+ SimGrid can use either pthreads library or the UNIX98 contextes. On
+ most systems, the number of pthreads is limited and then your
+ simulation may be limited for a stupid reason. This is especially
+ true with the current linux pthreads, and I cannot get more than
+ 2000 simulated processes with pthreads on my box. The UNIX98
+ contexts allow me to raise the limit to 25,000 simulated processes
+ on my laptop.\n\n
+ The --with-context option of the ./configure
+ script allows you to choose between UNIX98 contextes
+ (--with-context=ucontext) and the pthread version
+ (--with-context=pthread). The default value is ucontext
+ when the script detect a working UNIX98 context implementation. On
+ Windows boxes, the provided value is discarded and an adapted
+ version is picked up.\n\n
+ We experienced some issues with contextes on some rare systems
+ (solaris 8 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 ;)
+
+ - Hundred thousands of simulated processes (hard-core tricks)\n
+ As explained above, SimGrid can use UNIX98 contextes to represent
+ and handle the simulated processes. Thanks to this, the main
+ limitation to the number of simulated processes becomes the
+ available memory.\n\n
+ Here are some tricks I had to use in order to run a token ring
+ between 25,000 processes on my laptop (1Gb memory, 1.5Gb swap).\n
+ - First of all, make sure your code runs for a few hundreds
+ processes before trying to push the limit. Make sure it's
+ valgrind-clean, ie that valgrind does not report neither memory
+ error nor memory leaks. Indeed, numerous simulated processes
+ result in *fat* simulation hindering debugging.
+ - It was really boring to write 25,000 entries in the deployment
+ file, so I wrote a little script
+ examples/gras/tokenS/make_deployment.pl, which you may
+ want to adapt to your case. You could also think about hijacking
+ the SURFXML parser (have look at \ref faq_flexml_bypassing).
+ - The deployment file became quite big, so I had to do what is in
+ the FAQ entry \ref faq_flexml_limit
+ - Each UNIX98 context has its own stack entry. As debugging this is
+ quite hairly, the default value is a bit overestimated so that
+ user don't get into trouble about this. You want to tune this
+ size to increse the number of processes. This is the
+ STACK_SIZE define in
+ src/xbt/context_private.h, which is 128kb by default.
+ Reduce this as much as you can, but be warned that if this value
+ is too low, you'll get a segfault. The token ring example, which
+ is quite simple, runs with 40kb stacks.
+
+\subsubsection 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
+generic way is thus very hard). However some people have implemented
+their own batch schedulers. Vincent Garonne wrote one during his PhD
+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.
+
+\subsubsection 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
+rewind 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.
+
+\subsection faq_platform Platform building and Dynamic resources
+
+\subsubsection faq_platform Building a realistic platform
+
+We can speak more than an hour on this subject and we still do not have
+the right answer, just some ideas. You can read the following
+slides.
+It may give you some hints. You can also have a look at the
+tools/platform_generation/ directory. There is a perl-script
+we use to annotate a Tiers generated platform.
-\subsection faq_SURF_dynami How can I have variable resource availability?
+\subsubsection faq_SURF_dynamic Building a dynamic platform, with resource availability
A nice feature of SimGrid is that it enables you to seamlessly have
resources whose availability change over time. When you build a
@@ -412,10 +853,10 @@ PERIODICITY 1.0
20.0 0.9
\endverbatim
-At time 0, our CPU will deliver 100 Mflop/s. At time 11.0, it will
-deliver only 50 Mflop/s until time 20.0 where it will will start
-delivering 90 Mflop/s. Last at time 21.0 (20.0 plus the periodicity
-1.0), we'll be back to the beginning and it will deliver 100Mflop/s.
+At time 0, our CPU will deliver 100 flop/s. At time 11.0, it will
+deliver only 50 flop/s until time 20.0 where it will will start
+delivering 90 flop/s. Last at time 21.0 (20.0 plus the periodicity
+1.0), we'll be back to the beginning and it will deliver 100 flop/s.
Now let's look at the state file:
\verbatim
@@ -439,9 +880,9 @@ links. A usual declaration looks like:
You have at your disposal the following options: bandwidth_file,
latency_file and state_file. The only difference with CPUs is that
bandwidth_file and latency_file do not express fraction of available
-power but are expressed directly in Mb/s and seconds.
+power but are expressed directly in bytes per seconds and seconds.
-\section faq_flexml_bypassing How could I have some C functions do what the platform and deployment files do?
+\subsubsection faq_flexml_bypassing Bypassing the XML parser with your own C functions
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
@@ -511,7 +952,60 @@ Then, tell SimGrid that you want to use your own "parser" instead of the stock o
An example of this trick is distributed in the file examples/msg/msg_test_surfxml_bypassed.c
-\section faq_flexml_limit I get the message "surf_parse_lex: Assertion `nextYou are using a borken build environment\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.
+
+\subsubsection faq_trouble_distcheck Dude! "make check" fails on my machine!
+
+Don't assume we never run this target, because we do. Check
+http://bob.loria.fr:8010 if you don't believe us.
+
+There is several reasons which may cause the make check to fail on your
+machine:
+
+ - You are using a borken libc (probably concerning the contextes).\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. There is not much we can do to fix the bug.
+ A workaround is to 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.\n
+ => use --with-pthread on AMD64 architecture that do not have an
+ ultra-recent libc.
+
+ - There is a bug in SimGrid we aren't aware of.\n
+ If none of the above apply, please drop us a mail on the mailing list so
+ that we can check it out. Make sure to read \ref faq_bugrepport
+ before you do so.
+
+\subsection faq_trouble_errors Understanding error messages
+
+\subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)"
+
+This is because you are using the log mecanism, but you didn't created
+any default category in this file. You should refer to \ref XBT_log
+for all the details, but you simply forgot to call one of
+XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY().
+
+\subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."
This is because your platform file is too big for the parser.
@@ -547,43 +1041,232 @@ These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
the development of FleXML, I can grant you that any patches would be really
welcome and quickly integrated.
-\section faq_host_load Where is the get_host_load function hidden in MSG?
+Update: A new version of FleXML (1.7) was released. Most of the work
+was done by William Dowling, who use it in his own work. The good point is
+that it now use a dynamic buffer, and that the memory usage was greatly
+improved. The downside is that William also changed some things internally,
+and it breaks the hack we devised to bypass the parser, as explained in
+\ref faq_flexml_bypassing. Indeed, this is not a classical usage of the
+parser, and Will didn't imagine that we may have used (and even documented)
+such a crude usage of FleXML. So, we now have to repare the bypassing
+functionnality to use the lastest FleXML version and fix the memory usage in
+SimGrid.
+
+\subsubsection faq_trouble_gras_transport GRAS spits networking error messages
+
+Gras, on real platforms, naturally use regular sockets to communicate. They
+are deeply hiden in the gras abstraction, but when things go wrong, you may
+get some weird error messages. Here are some example, with the probable
+reason:
+
+ - Transport endpoint is not connected: several processes try to open
+ a server socket on the same port number of the same machine. This is
+ naturally bad and each process should pick its own port number for this.\n
+ Maybe, you just have some processes remaining from a previous experiment
+ on your machine.\n
+ Killing them may help, but again if you kill -KILL them, you'll have to
+ wait for a while: they didn't close there sockets properly and the system
+ needs a while to notice that this port is free again.
+
+ - Socket closed by remote side: if the remote process is not
+ supposed to close the socket at this point, it may be dead.
+
+ - Connection reset by peer: I found this on internet about this
+ error. I think it's what's happening here, too:\n
+ This basically means that a network error occurred while the client was
+ receiving data from the server. But what is really happening is that the
+ server actually accepts the connection, processes the request, and sends
+ a reply to the client. However, when the server closes the socket, the
+ client believes that the connection has been terminated abnormally
+ because the socket implementation sends a TCP reset segment telling the
+ client to throw away the data and report an error.\n
+ Sometimes, this problem is caused by not properly closing the
+ input/output streams and the socket connection. Make sure you close the
+ input/output streams and socket connection properly. If everything is
+ closed properly, however, and the problem persists, you can work around
+ it by adding a one-second sleep before closing the streams and the
+ socket. This technique, however, is not reliable and may not work on all
+ systems.\n
+ Since GRAS sockets are closed properly (repeat after me: there is no bug
+ in GRAS), it is either that you are closing your sockets on server side
+ before the client get a chance to read them (use gras_os_sleep() to delay
+ the server), or the server died awfully before the client got the data.
+
+\subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old.
+
+We have decided to change the units in SimGrid. Now we use Bytes, Flops and
+seconds instead of MBytes, MFlops and seconds... Units should be updated
+accordingly and the version of platform_description should be set to a
+valuer greater than 1:
+\verbatim
+
+\endverbatim
+You should try to use the surfxml_update.pl script that can be found
+here.
-There is no such thing because its semantic wouldn't be really clear. Of
-course, it is something about the amount of host throughput, but there is as
-many definition of "host load" as people asking for this function.
+\subsection faq_trouble_valgrind Valgrind-related issues
-It may be instantaneous value or an average one. Moreover it may be only the
-power of the computer, or may take the background load into account, or may
-even take the currently running tasks into account. In some SURF models,
-communications have an influence on computational power. Should it be taken
-into account too?
+If you don't, you really should use valgrind to debug your code, it's
+almost magic.
-So, we decided not to include such a function into MSG and let people do it
-thereselves so that they get the value matching exactly what they mean. One
-possibility is to run active measurement as in next code snippet. It is very
-close from what you would have to do out of the simulator, and thus gives
-you information that you could also get in real settings to not hinder the
-realism of your simulation.
+\subsubsection faq_trouble_vg_longjmp longjmp madness in valgrind
-\verbatim
-double get_host_load() {
- m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
- double date = MSG_get_clock();
+This is when valgrind starts complaining about longjmp things, just like:
- MSG_task_execute(task);
- date = MSG_get_clock() - date;
- MSG_task_destroy(task);
- return (0.001/date);
-}
+\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
-Of course, it may not match your personal definition of "host load". In this
-case, please detail what you mean on the mailing list, and we will extend
-this FAQ section to fit your taste if possible.
+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 return; somewhere within a TRY{}
+block. This is evil, and you must not do this. Did you read the section
+about \ref XBT_ex??
+
+\subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces!
+
+It may happen that valgrind, the memory debugger beloved by any decent C
+programmer, spits tons of warnings like the following :
+\verbatim ==8414== Conditional jump or move depends on uninitialised value(s)
+==8414== at 0x400882D: (within /lib/ld-2.3.6.so)
+==8414== by 0x414EDE9: (within /lib/tls/i686/cmov/libc-2.3.6.so)
+==8414== by 0x400B105: (within /lib/ld-2.3.6.so)
+==8414== by 0x414F937: _dl_open (in /lib/tls/i686/cmov/libc-2.3.6.so)
+==8414== by 0x4150F4C: (within /lib/tls/i686/cmov/libc-2.3.6.so)
+==8414== by 0x400B105: (within /lib/ld-2.3.6.so)
+==8414== by 0x415102D: __libc_dlopen_mode (in /lib/tls/i686/cmov/libc-2.3.6.so)
+==8414== by 0x412D6B9: backtrace (in /lib/tls/i686/cmov/libc-2.3.6.so)
+==8414== by 0x8076446: xbt_dictelm_get_ext (dict_elm.c:714)
+==8414== by 0x80764C1: xbt_dictelm_get (dict_elm.c:732)
+==8414== by 0x8079010: xbt_cfg_register (config.c:208)
+==8414== by 0x806821B: MSG_config (msg_config.c:42)
+\endverbatim
+
+This problem is somewhere in the libc when using the backtraces and there is
+very few things we can do ourselves to fix it. Instead, here is how to tell
+valgrind to ignore the error. Add the following to your ~/.valgrind.supp (or
+create this file on need). Make sure to change the obj line according to
+your personnal mileage (change 2.3.6 to the actual version you are using,
+which you can retrieve with a simple "ls /lib/ld*.so").
+
+\verbatim {
+ name: Backtrace madness
+ Memcheck:Cond
+ obj:/lib/ld-2.3.6.so
+ fun:dl_open_worker
+ fun:_dl_open
+ fun:do_dlopen
+ fun:dlerror_run
+ fun:__libc_dlopen_mode
+}\endverbatim
+
+Then, you have to specify valgrind to use this suppression file by passing
+the --suppressions=$HOME/.valgrind.supp option on the command line.
+You can also add the following to your ~/.bashrc so that it gets passed
+automatically. Actually, it passes a bit more options to valgrind, and this
+happen to be my personnal settings. Check the valgrind documentation for
+more information.
+
+\verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" \endverbatim
+
+\subsection faq_deadlock There is a deadlock in my code!!!
+
+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_visualization FAQ entry to see
+how to get a graphical one.
+
+Now, if you come up with a really simple example that deadlocks and
+you're absolutely convinced that it should not, you can ask on the
+list. Just be aware that you'll be severely punished if the mistake is
+on your side... We have plenty of FAQ entries to redact and new
+features to implement for the impenitents! ;)
+
+\subsection faq_surf_network_latency I get weird timings when I play with the latencies.
+
+OK, first of all, remember that units should be Bytes, Flops and
+Seconds. If you don't use such units, some SimGrid constants (e.g. the
+SG_TCP_CTE_GAMMA constant used in most network models) won't have the
+right unit and you'll end up with weird results.
+
+Here is what happens with a single transfer of size L on a link
+(bw,lat) when nothing else happens.
+
+\verbatim
+0-----lat--------------------------------------------------t
+|-----|**** real_bw =min(bw,SG_TCP_CTE_GAMMA/(2*lat)) *****|
+\endverbatim
-\author Arnaud Legrand (arnaud.legran::imag.fr)
+In more complex situations, this min is the solution of a complex
+max-min linear system. Have a look
+here
+and read the two threads "Bug in SURF?" and "Surf bug not
+fixed?". You'll have a few other examples of such computations. You
+can also read "A Network Model for Simulation of Grid Application" by
+Henri Casanova and Loris Marchal to have all the details. The fact
+that the real_bw is smaller than bw is easy to understand. The fact
+that real_bw is smaller than SG_TCP_CTE_GAMMA/(2*lat) is due to the
+window-based congestion mechanism of TCP. With TCP, you can't exploit
+your huge network capacity if you don't have a good round-trip-time
+because of the acks...
+
+Anyway, what you get is t=lat + L/min(bw,SG_TCP_CTE_GAMMA/(2*lat)).
+
+ * if I you set (bw,lat)=(100 000 000, 0.00001), you get t = 1.00001 (you fully
+use your link)
+ * if I you set (bw,lat)=(100 000 000, 0.0001), you get t = 1.0001 (you're on the
+limit)
+ * if I you set (bw,lat)=(100 000 000, 0.001), you get t = 10.001 (ouch!)
+
+This bound on the effective bandwidth of a flow is not the only thing
+that may make your result be unexpected. For example, two flows
+competing on a saturated link receive an amount of bandwidth inversely
+proportional to their round trip time.
+
+\subsection faq_bugrepport So I've found a bug in SimGrid. How to report it?
+
+We do our best to make sure to hammer away any bugs of SimGrid, but this is
+still an academic project so please be patient if/when you find bugs in it.
+If you do, the best solution is to drop an email either on the simgrid-user
+or the simgrid-devel mailing list and explain us about the issue. You can
+also decide to open a formal bug report using the
+relevant
+interface. You need to login on the server to get the ability to submit
+bugs.
+
+We will do our best to solve any problem repported, but you need to help us
+finding the issue. Just telling "it segfault" isn't enough. Telling "It
+segfaults when running the attached simulator" doesn't really help either.
+You may find the following article interesting to see how to repport
+informative bug repports:
+http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid
+specific at all, but it's full of good advices).
+
+\author Arnaud Legrand (arnaud.legrand::imag.fr)
\author Martin Quinson (martin.quinson::loria.fr)
+\endhtmlonly
+