doc/FAQ.doc

   1 /*! \page faq Frequently Asked Questions
   2
   3 \author Arnaud Legrand <arnaud.legrand#imag.fr>
   4
   5 \section faq_installation Installing the SimGrid library
   6
   7 Many people have been asking me questions on how to use SimGrid. Quite
   8 often, the questions were not really about SimGrid but on the
   9 installation process. This section is intended to help people that are
  10 not familiar with compiling C files under UNIX. If you follow these
  11 instructions and still have some troubles, drop an e-mail to
  12 <simgrid-user@lists.gforge.inria.fr>.
  13
  14 \subsection faq_compiling Compiling SimGrid
  15
  16 Suppose you have uncompressed SimGrid in some temporary location of
  17 your home directory (say <tt>/home/joe/tmp/simgrid-2.18.2 </tt>). The
  18 simplest way to use SimGrid is to install it in your home
  19 directory. Change your directory to
  20 <tt>/home/joe/tmp/simgrid-2.18.2</tt> and type
  21
  22 \verbatim./configure --prefix=$HOME
  23 make
  24 make install
  25 \endverbatim
  26
  27 If at some point, something fails, you can report me this problem but,
  28 please, avoid sending a laconic mail like "There is a problem. Is it
  29 normal ?". Send me the config.log file which is automatically
  30 generated by configure. Try to capture both the standard output and
  31 the error output of the <tt>make</tt> command. There is no way for me
  32 to help you if you do not give me a little bit of information.
  33
  34 Now, the following directory should have been created :
  35
  36       \li <tt>/home/joe/doc/simgrid/html/</tt>
  37       \li <tt>/home/joe/lib/</tt>
  38       \li <tt>/home/joe/include/</tt>
  39
  40 SimGrid is not a binary, it is a library. Both a static and a dynamic
  41 version are available. Here is what you can find if you try a <tt>ls
  42 /home/joe/lib</tt>:
  43
  44 \verbatim libsimgrid.a  libsimgrid.la  libsimgrid.so  libsimgrid.so.0 libsimgrid.so.0.0.1
  45 \endverbatim
  46
  47 Thus, there is two ways to link your program with SimGrid:
  48       \li Either you use the static version, e.g
  49 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
  50 \endverbatim
  51           In this case, all the SimGrid functions are directly
  52           included in <tt>MainProgram</tt> (hence a bigger binary).
  53       \li Either you use the dynamic version (the preferred method)
  54 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
  55 \endverbatim
  56           In this case, the SimGrid functions are not included in
  57           <tt>MainProgram</tt> and you need to set your environment
  58           variable in such a way that <tt>libsimgrid.so</tt> will be
  59           found at runtime. This can be done by adding the following
  60           line in your .bashrc (if you use bash and if you have
  61           installed the SimGrid libraries in your home directory):
  62 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
  63 \endverbatim
  64
  65 \subsection faq_setting Setting up your own code
  66
  67 Do not build your simulator by modifying the SimGrid examples.  Go
  68 outside the SimGrid source tree and create your own working directory
  69 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
  70
  71 Suppose your simulation has the following structure (remember it is
  72 just an example to illustrate a possible way to compile everything;
  73 feel free to organize it as you want).
  74
  75       \li <tt>sched.h</tt>: a description of the core of the
  76           scheduler (i.e. which functions are can be used by the
  77           agents). For example we could find the following functions
  78           (master, forwarder, slave).
  79
  80       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
  81           implementing the core of the scheduler. Most of these
  82           functions use the MSG functions defined in section \ref
  83           msg_gos_functions.
  84
  85       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
  86           the MSG initialization (MSG_global_init()), the platform
  87           creation (e.g. with MSG_create_environment()), the
  88           deployment phase (e.g. with MSG_function_register() and
  89           MSG_launch_application()) and the call to
  90           MSG_main()).
  91
  92 To compile such a program, I suggest to use the following Makefile. It
  93 is a generic Makefile that I generally use with my students when I
  94 teach the C language.
  95
  96 \verbatim
  97 all: masterslave
  98 masterslave: masterslave.o sched.o
  99
 100 INSTALL_PATH = $$HOME
 101 CC = gcc
 102 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
 103                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
 104                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
 105                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
 106                                 -Wpointer-arith -Wwrite-strings -finline-functions
 107 REASONABLY_CAREFUL_DUDE =       -Wall
 108 NO_PRAYER_FOR_THE_WICKED =      -w -O2
 109 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
 110 CFLAGS = -g $(WARNINGS)
 111
 112 INCLUDES = -I$(INSTALL_PATH)/include
 113 DEFS = -L$(INSTALL_PATH)/lib/
 114 LDADD = -lm -lsimgrid
 115 LIBS =
 116
 117 %: %.o
 118         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
 119
 120 %.o: %.c
 121         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
 122
 123 clean:
 124         rm -f $(BIN_FILES) *.o *~
 125 .SUFFIXES:
 126 .PHONY : clean
 127
 128 \endverbatim
 129
 130 The first two lines indicates what should be build when typing make
 131 (<tt>masterslave</tt>) and of which files it is to be made of
 132 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
 133 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
 134 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
 135 the static version, remove the <tt>-lsimgrid</tt> and add a
 136 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
 137 after the <tt>LIBS = </tt>.
 138
 139 More generally, if you have never written a Makefile by yourself, type
 140 in a terminal : <tt>info make</tt> and read the introduction. The
 141 previous example should be enough for a first try but you may want to
 142 perform some more complex compilations...
 143
 144 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start ?
 145
 146 You are at the right place... Having a look to these <a
 147 href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>
 148 may give you some insights on what SimGrid can help you to do and what
 149 are its limitations. Then you definitely should read the \ref
 150 MSG_examples. There is also a mailing list: <simgrid-user#lists.gforge.inria.fr>.
 151
 152 \subsection faq_generic Building a generic simulator
 153
 154 Please read carefully the \ref MSG_examples. You'll find in \ref
 155 MSG_ex_master_slave a very simple consisting of a master (that owns a bunch of
 156 tasks and distributes them) , some slaves (that process tasks whenever
 157 they receive one) and some forwarder agents (that simply pass the
 158 tasks they receive to some slaves).
 159
 160 \subsection faq_examples I want some more complex examples !
 161
 162 Many people have come to ask me a more complex example and each time,
 163 they have realized afterward that the basics were in the previous three
 164 examples.
 165
 166 Of course they have often been needing more complex functions like
 167 MSG_process_suspend(), MSG_process_resume() and
 168 MSG_process_isSuspended() (to perform synchronization), or
 169 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
 170 receptions), or even MSG_process_create() (to design asynchronous
 171 communications or computations). But the examples are sufficient to
 172 start.
 173
 174 I know I should add some more examples, but not some more complex
 175 ones... I should add some examples that illustrate some other
 176 functionalities (like how to simply encode asynchronous
 177 communications, RPC, process migrations, thread synchronization, ...)
 178 and I will do it when I will have a little bit more time. I have tried
 179 to document the examples so that they are understandable. I know it is
 180 not really satisfying but it is the best I have managed to do yet.
 181
 182 \subsection faq_platform Building a realistic platform
 183
 184 I can speak more than an hour on this subject and I still do not have
 185 the right answer, just some ideas. You can read the following <a
 186 href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
 187 It may give you some hints. You can also have a look at the
 188 <tt>tools/platform_generation/</tt> directory. There is a perl-script
 189 I use to annotate a Tiers generated platform (may not be up-to-date
 190 though).
 191
 192 \subsection faq_visualization Visualizing the schedule
 193
 194 It is sometime convenient to "see" how the agents are behaving. If you
 195 like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
 196 as a filter to your MSG outputs. It works directly with INFO. Beware,
 197 INFO() prints on stderr. Do not forget to redirect if you want to
 198 filter (e.g. with bash):
 199 \verbatim
 200 ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
 201 \endverbatim
 202
 203 We also have a more graphical output. Have a look at MSG_paje_output(). It
 204 generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
 205 <center>
 206 \htmlonly
 207  <a href="Paje_MSG_screenshot.jpg"><img src="Paje_MSG_screenshot_thn.jpg"></a>
 208 \endhtmlonly
 209 </center>
 210
 211 \subsection faq_context I have tons of process and it is limiting my simulation.
 212
 213 MSG can use either pthreads or the GNU context library. On most
 214 systems, the number of pthreads is limited (especially with the
 215 current linux pthreads) and then your simulation may be limited for a
 216 stupid reason. If you enable the context option
 217 (<tt>--enable-context</tt> in the <tt>./configure</tt> phase), you
 218 will not use the pthread anymore and the context switching will be
 219 done manually, which enables us to have as much agents as your memory
 220 can hold and should be much faster... So think about it if your
 221 simulation is getting really big.
 222
 223 Nevertheless, be aware that this code does not work on some system. It
 224 is not very clean. As usual, as soon as I will have a little bit more
 225 time, I will recode it in a cleaner way.
 226
 227 \section faq_SG Where has SG disappeared ?!?
 228
 229 OK, it's time to explain what's happening to the SimGrid project. Let's
 230 start with a little bit of history.
 231
 232 * Historically, SimGrid was a low-level toolkit for scheduling with
 233 classical models such as DAGs. That was SimGrid v.1.* aka SG, written by
 234 Henri Casanova. I had been using it in its earliest versions during an
 235 internship at UCSD.
 236
 237 Then we have realized that encoding distributed algorithm in SG was a
 238 real pain.
 239
 240 * So we have built MSG on top of SG and have released SimGrid v.2.*. MSG
 241 offered a very basic API to encode a distributed application easily.
 242 However encoding MSG on top of SG was not really convenient and did not
 243 use the DAG part since the control of the task synchronization was done
 244 on top of MSG and no more in SG. We have been playing a little bit with
 245 MSG. We have realized that:
 246
 247    \li 1) the platform modeling was quite flexible and could be "almost"
 248        automated (e.g. using random generator and post-annotations);
 249
 250    \li 2) SG was the bottleneck because of the way we were using
 251        it. We needed to simulate concurrent transfers, complex load
 252        sharing mechanisms. Many optimizations (e.g. trace integration)
 253        were totally inefficient when combined with MSG and made extending SG
 254        to implement new sharing policies, parallel tasks models, or failures
 255        (many people were asking for these kind of features) a real pain;
 256
 257    \li 3) the application modeling was not really easy. Even though the
 258        application modeling depends on people's applications, we thought
 259        we could improve things here. One of our target here was realistic
 260 distributed applications ranging from computer sensor networks like
 261 the NWS to peer-to-peer applications;
 262
 263 * So we have been planning mainly two things for SimGrid 3:
 264
 265    \li 1) I have proposed to get rid of SG and to re-implement a new kernel
 266        that would be faster and more flexible. That is what I did in the
 267 end of 2004: SURF. SURF is based on a fast max-min linear solver
 268 using O(1) data-structures. I have quickly replaced SG by SURF in
 269 MSG and the result has been that on the MSG example, the new
 270 version was more than 10 times faster while we had gain a lot of
 271 flexibility. I think I could still easily make MSG faster but I
 272 have to work on MSG now (e.g. using some of the O(1)
 273 data-structures I've been using to build SURF) since it has become
 274 the bottleneck. Some MSG functions have been removed from the API
 275 but they were mainly intended to build the platform by hand (they
 276 had appeared in the earliest versions of MSG) and were therefore
 277 not useful anymore since we are providing a complete mechanism to
 278 automatically build the platform and deploy the agents on it.;
 279
 280    \li 2) GRAS is a new project Martin and I have come up with. The idea is
 281 to have a programming environment that let you program real
 282 distributed applications while letting you the ability to run it in
 283 the simulator without having to change the slightest line of your
 284 code. From the simulation point of view, GRAS performs the
 285 application modeling automatically... Up until now, GRAS works on
 286 top MSG for historical reasons but I'm going to make it work
 287 directly on top of SURF so that it can use all the flex and the
 288 speed provided by SURF.
 289
 290 Those two things are working, but we want to make everything as clean as
 291 possible before releasing SimGrid v.3.
 292
 293 So what about those nice DAGs we used to have in SimGrid v.1. ? They're not
 294 anymore in SimGrid v.3. Let me recall you the way SimGrid 3 is organized:
 295
 296 \verbatim
 297 ________________
 298 |   User code  |
 299 |______________|
 300 | | MSG | GRAS |
 301 | -------------|
 302 | |   SURF     |
 303 | -------------|
 304 |     XBT      |
 305 ----------------
 306 \endverbatim
 307
 308 XBT is our tool box and now, you should have an idea of what the other ones
 309 are. As you can see, the primitive SG is not here anymore. However it could
 310 still be brought back if people really need it. Here is how it would fit.
 311
 312 \verbatim
 313 ______________________
 314 |    User code       |
 315 |____________________|
 316 | | MSG | GRAS | SG  |
 317 | -------------------|
 318 | |      SURF        |
 319 | -------------------|
 320 |        XBT         |
 321 ----------------------
 322 \endverbatim
 323
 324 Re-implementing SG on top of SURF is really straightforward (it only
 325 requires a little bit of time that I really don't have right now)
 326 since the only thing that lacks to SURF is the DAG part. But adding it
 327 to SURF would slow it down and therefore slow MSG and GRAS which is
 328 not a good thing.  However it is really not on the top of our TODO
 329 list because we have to work on GRAS, and its MPI counterpart, and a
 330 parallel task model, and ... Anyway, we finally have migrated our CVS
 331 to gforge so people that are interested by helping on this part will
 332 have the possibility to do it.
 333
 334 \subsection 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 ?
 335
 336 Distributed is somehow "contagious". If you start making distributed
 337 decisions, there is no way to handle DAGs directly anymore (unless I am
 338 missing something). You have to encode your DAGs in term of communicating
 339 process to make the whole scheduling process distributed. Believe me, it is
 340 worth the effort since you'll then be able to try your algorithms in a very
 341 wide variety of conditions.
 342
 343 If you decide that the distributed part is not that much important and that
 344 DAG is really the level of abstraction you want to work with (but it
 345 prevents you from having "realistic" platform modeling), then you should
 346 keep using the 2.18.5 versions until somebody has ported SG on top of SURF.
 347 Note however that SURF will be slower than the old SG to handle traces with
 348 a lots of variations (there is no trace integration anymore).
 349
 350 */