Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Kill another bunch of files in doc/ and move their content to docs/
[simgrid.git] / doc / doxygen / FAQ.doc
index db3f7cb..4f8f178 100644 (file)
@@ -1,138 +1,6 @@
-/*! @page FAQ MSG Frequently Asked Questions
+/*! @page FAQ Frequently Asked Questions
 
-@tableofcontents
-
-This document is the FAQ of the MSG interface. Some entries are a bit aging and it should be refreshed at some point.
-
-@section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
-
-You are at the right place... To understand what you can do or
-cannot do with SimGrid, you should read the
-<a href="https://simgrid.org/tutorials.html">tutorial
-slides</a> from the SimGrid's website. You may find more up-to-date
-material on the
-<a href="http://people.irisa.fr/Martin.Quinson/blog/SimGrid/">blog of
-Martin Quinson</a>.
-
-Another great source of inspiration can be found in the @ref s4u_examples.
-
-If you are stuck at any point and if this FAQ cannot help you, please drop us a
-mail to the user mailing list: <simgrid-community@inria.fr>.
-
-@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 <tt>tools/MSG_visualization/colorize.pl </tt>
-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 section @ref options_tracing.
-
-@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, ...) is
-meant to be kept as simple and generic as possible. We cannot add
-functions for everybody's needs 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_thread_synchronization How to synchronize my user processes?
-
-It depends on why you want to synchronize them.  If you just want to
-have a shared state between your processes, then you probably don't
-need to do anything. User processes never get forcefully interrupted
-in SimGrid (unless you explicitly request the parallel execution of
-user processes -- see @ref options_virt_parallel).
-
-Even if several processes are executed at the exact same time within
-the simulation, they are linearized in reality by default: one process
-always run in an exclusive manner, atomic, uninterrupted until it does
-a simcall (until it ask a service from the simulation kernel). This is
-surprising at first, but things are much easier this way, both for the
-user (who don't have to protect her shared data) and for the kernel
-(that avoid many synchronization issues too). Processes are executed
-concurrently in the simulated realm, but you don't need to bother with
-this in the real realm.
-
-If you really need to synchronize your processes (because it's what
-you are studying or to create an atomic section that spans over
-several simcalls), you obviously cannot use regular synchronization
-mechanisms (pthread_mutexes in C or the synchronized keyword in Java).
-This is because the SimGrid kernel locks all processes and unlock them
-one after the other when they are supposed to run, until they give the
-control back in their simcall. If one of them gets locked by the OS
-before returning the control to the kernel, that's definitively a
-deadlock.
-
-Instead, you should use the synchronization mechanism provided by the
-simulation kernel. This could with a SimGrid mutex, a SimGrid
-condition variables or a SimGrid semaphore, as described in @ref
-msg_synchro (in Java, only semaphores are available). But actually,
-many synchronization patterns can be encoded with communication on
-mailboxes. Typically, if you need one process to notify another one,
-you could use a condition variable or a semaphore, but sending a
-message to a specific mailbox does the trick in most cases.
-
-@subsubsection faq_MIA_communication_time How can I get the *real* communication time?
-
-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.
-
-@code
-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, workers[i % workers_count], PORT_22);
-  XBT_INFO("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);
-  XBT_INFO("Communication time :  \"%f\" ", time2-time1);
-  free(task->data);
-  MSG_task_destroy(task);
-  return 0;
-}
-@endcode
-
-@subsection faq_MIA_SimDag SimDag related questions
-
-@subsubsection faq_SG_comm Implementing communication delays between tasks.
+@subsubsection Implementing communication delays between SimDAG tasks.
 
 A classic question of SimDag newcomers is about how to express a
 communication delay between tasks. The thing is that in SimDag, both
@@ -157,114 +25,4 @@ comprising the workstations on which t1 and t2 are scheduled (w1 and w2
 for example) and build a communication matrix that should look like
 [0;amount ; 0; 0].
 
-@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. Here is an example of how you could do that. Assume T1
-has to be done before T2.
-
-@code
- 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 */
-     }
-   }
- }
-@endcode
-
-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, then you should
-give a try to @ref SD_API.
-
-@subsection faq_MIA_generic Generic features
-
-@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 SVN so that other can
-keep working on it. You may find inspiring ideas in it.
-
-@subsection faq_platform Platform building and Dynamic resources
-
-@subsubsection faq_platform_synthetic Generating synthetic but realistic platforms
-
-Another possibility to get a platform file is to generate synthetic
-platforms. Getting a realistic result is not a trivial task, and
-moreover, nobody is really able to define what "realistic" means when
-speaking of topology files. You can find some more thoughts on this
-topic in these
-<a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
-
-If you are looking for an actual tool, there we have a little tool to
-annotate Tiers-generated topologies. This perl-script is in
-<tt>tools/platform_generation/</tt> directory of the SVN. Dinda et Al.
-released a very comparable tool, and called it GridG.
-
-
-The specified computing power will be available to up to 6 sequential
-tasks without sharing. If more tasks are placed on this host, the
-resource will be shared accordingly. For example, if you schedule 12
-tasks on the host, each will get half of the computing power. Please
-note that although sound, this model were never scientifically
-assessed. Please keep this fact in mind when using it.
-
-@section faq_troubleshooting Troubleshooting
-
-@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
-
-In more complex situations, this min is the solution of a complex
-max-min linear system.  Have a look
-<a href="http://lists.gforge.inria.fr/pipermail/simgrid-devel/2006-April/thread.html">here</a>
-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.
-
 */