X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/4e62e76d104a17f0c9aaf9135ac605e9c8c87141..20f5604e5582663868f57fb5db28a88929ac3d43:/doc/doxygen/FAQ.doc diff --git a/doc/doxygen/FAQ.doc b/doc/doxygen/FAQ.doc index 2509ee9f1d..4f8f178d99 100644 --- a/doc/doxygen/FAQ.doc +++ b/doc/doxygen/FAQ.doc @@ -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 -tutorial -slides from the SimGrid's website. You may find more uptodate -material on the -blog of -Martin Quinson. - -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: . - -@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 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 semphore, 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, slaves[i % slaves_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,199 +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_example Where can I find SimGrid platform files? - -There are several little examples in the archive, in the examples/platforms -directory. From time to time, we are asked for other files, but we -don't have much at hand right now. - -You should refer to the Platform Description Archive -(http://pda.gforge.inria.fr) project to see the other platform file we -have available, as well as the Simulacrum simulator, meant to generate -SimGrid platforms using all classical generation algorithms. - -@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 -slides. - -If you are looking for an actual tool, there we have a little tool to -annotate Tiers-generated topologies. This perl-script is in -tools/platform_generation/ 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_trouble_compil User code compilation problems - -@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 mechanism, 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(). - -@subsection faq_trouble_errors Runtime error messages - -@subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old. - -The format of the XML platform description files is sometimes -improved. For example, we decided to change the units used in SimGrid -from MBytes, MFlops and seconds to Bytes, Flops and seconds to ease -people exchanging small messages. We also reworked the route -descriptions to allow more compact descriptions. - -That is why the XML files are versioned using the 'version' attribute -of the root tag. Currently, it should read: -@verbatim - -@endverbatim - -If your files are too old, you can use the simgrid_update_xml.pl -script which can be found in the tools directory of the archive. - -@subsection faq_trouble_debug Debugging SMPI applications - -In order to debug SMPI programs, you can use the following options: - -- -wrapper 'gdb --args': this option is used to use a wrapper - in order to call the SMPI process. Good candidates for this options - are "gdb --args", "valgrind", "rr record", "strace", etc; - -- -foreground: this options gives the debugger access to the terminal - which is needed in order to use an interactive debugger. - -Both options are needed in order to run the SMPI process under GDB. - -@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 information 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 - -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 reported, 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 report -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). - */