Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
0a8cbbdb3ab06988cac429af4099e2592c01ed6d
[simgrid.git] / doc / doxygen / bindings.doc
1 /*! \page bindings Bindings
2
3 \section bindings_binding_Ruby Ruby Binding
4 Check online for our specific [Simgrid-Ruby documentation](http://simgrid.gforge.inria.fr/documentation.html).
5
6 \section bindings_binding_Java Java Binding
7 Simgrid-java is a java API that let you use [Simgrid](http://simgrid.gforge.inria.fr/)
8 MSG API in your favorite language (java). Without it, you would be forced to
9 use C or one of the other bindings provided.
10
11 MSG was the first distributed programming environment provided within SimGrid.
12 While almost realistic, it remains quite simple. This describes the Java
13 bindings to this interface.
14
15 The javadoc is accessible [here](javadoc/index.html)
16
17 \subsection bindings_binding_Java_jMSG_who Who should use this (and who shouldn't)
18 You should use MSG if you want to study some heuristics for a given problem you
19 don't really want to implement. SimGrid-java let you use MSG while coding in
20 Java. So if your need is MSG + Java, you're in the right section!
21
22 \subsection SimGrid-java Usage overview 
23
24 To make a long story short, it's a JNI binding, so it implies that:
25 - Most of the MSG and SimGrid documentation about behavioral aspects applies
26   directly to what you are programming. 
27 - MSG data structures are mapped to Java objects. So it means that from the
28   syntax point of view, you have to know how those objects are. Fortunately,
29   we have generated the Javadoc for those objects. So take a look at it
30
31 Finally, it implies also that your program can crash for 3 main reasons: 
32 - Your Java part is not good: you'll have a good old java exception thrown,
33   and hence you should be able to correct it by yourself.
34 - Our java part is not good: you'll also have a java exception thrown, but
35   we have real doubts this can happen, since the java part is only a JNI
36   binding. The other option is that it crashed because you used incorrectly
37   the MSG API, so this means also you should have an MSGException. It means
38   you should read carefully MSG samples and/or documentation.
39 - Something has crashed in the C part. Okay, here comes the tricky thing.
40
41 C crashes mainly for 2 reasons: 
42 - When something goes wrong in your simulation, sometimes the C part stops
43   because you used SimGrid incorrectly, and JNI bindings are not fond of that.
44   It means that you'll have something that looks ugly, but you should be able
45   to identify what's going wrong in your code by carefully reading the whole
46   error message
47 - It may happen that the problem comes directly from SimGrid: in this case,
48   the error should be uglier. In that case, you may submit a bug directly to
49   SimGrid.
50
51 \subsection bindings_binding_java_install How to install Simgrid-java
52
53 To use java with Simgrid you have to install some dependencies:
54 - Java JDK packages, such as `openjdk7` or `sun-java6-jdk` (with `libgcj10-dev` or another
55   version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see
56   \ref bindings_binding_java_coroutines).
57  
58 Then build Simgrid with the Java bindings enabled:
59 ~~~~{.sh}
60 cmake -Denable_java=ON .
61 ~~~~
62  
63 If cmake complains that **jni could not be found**, you need to tell it where
64 JNI header files are located. the following command should tell you:
65
66 ~~~~{.sh}
67 $ locate jni.h
68 /usr/lib/jvm/java-6-openjdk-amd64/include/jni.h
69 /usr/lib/jvm/java-7-openjdk-amd64/include/jni.h
70 ~~~~
71
72 If you have several version of jni installed (as in the example
73 above), you need to check the version of java that is used by default
74 on your machine (using javac -version), and pick the right one. Then
75 set the `JAVA_INCLUDE_PATH` environment variable to the right path (note
76 that we remove the filename `jni.h` from that path), and relaunch cmake.
77
78 ~~~~{.sh}
79 $ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/
80 $ cmake .
81 ~~~~
82
83 \subsubsection bindings_binding_java_use How to use Simgrid-java
84
85 To execute the examples you need to add the path where you installed
86 the generated `libSG_java` and `libsimgrid` libraries
87 into the `LD_LIBRARY_PATH`.
88
89 Be careful on Mac, this variable is called `DYLD_LIBRARY_PATH` and not
90 `LD_LIBRARY_PATH`.
91
92 ~~~~{.sh}
93 $ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
94 $ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
95 $ cd examples
96 $ java -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
97 ~~~~
98
99 If you want to make these settings permanent even after a reboot, you
100 need to add the export lines into your `~/.bashrc` file, or equivalent.
101
102 \subsubsection bindings_binding_java_coroutines How to use the coroutines context factory
103
104 There is two main motivations to use the coroutine variant of SimGrid
105 Java bindings: it's about 5 times faster than the default thread-based
106 context factory, and the amount of runnable processes is then only
107 limited by the amount of RAM that you have. The drawbacks are that it
108 requires a specific and rather experimental JVM to run, and that this
109 context factory itself remains a bit experimental so far.
110
111 \subsubsection  bindings_java_coro_install Getting a mlvm JVM
112
113 You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/)
114 (many thanks to Lukas Stadler for this work!). 
115
116 You can either get a prebuilt binary, or recompile your own JVM. Make
117 sure to get a coro-simple version, as we don't need to serialize nor
118 migrate stacks in SimGrid. You should be able to follow the `README.txt`
119 that you'll get in the repository, but here is how we did it, just in
120 case. The instructions are given for a debian or Ubuntu box, but I
121 think you should manage to convert it to your system quite easily.
122 Finally, if you're really stuck, you can get the version compiled by
123 Jonathan Rouzaud-Cornabas from his web page. This version is known to
124 work with SimGrid for sure!
125 http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
126  
127  -# Install mercurial and some dependencies
128 ~~~~{.sh}
129 sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
130 # Grab the forest extension: we need to source-install it
131 hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim
132 ~~~~
133  -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
134     following lines. Don't forget to change the /path/to/forest.py to
135     point to where you just downloaded the source. 
136     
137     Forest extension is needed to download the openjdk source code and
138     patches while the mq line is needed to apply the patches. The
139     username is needed at the step "preparing the sources", not sure why.
140 ~~~~
141 [ui]
142 username = YouUserameWithoutSpaces
143 [extensions]
144 forest=/path/to/forest.py
145 mq=
146 ~~~~
147  -# Prepare the source code
148 ~~~~{.sh}
149 # create a working directory, and enter it
150 mkdir davinci; cd davinci
151
152 # Grab the sources
153 hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
154 # Grab the patches
155 hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
156
157 # Link the patch directories into the sources
158 bash patches/make/link-patch-dirs.sh sources patches
159 # Test wether the previous command worked with
160 ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
161 # It should display something like the following.
162 # (note that both file share the same inode number)
163 #  9707849 patches/hotspot/series  
164 #  9707849 sources/hotspot/.hg/patches/series
165
166
167 # Specify what to compile. 
168 export davinci=$(pwd) guards="buildable testable coro-simple"
169 # Apply the patches
170 sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)'
171 # Check that it understood that you want the patch applied:
172 grep GLOBAL_GUARDS patches/make/* -r
173 # this should display something like the following (maybe amonst other unrelated lines)
174 # GLOBAL_GUARDS=buildable testable coro-simple
175 # If this does not work, edit patches/make/Makefile,
176 #   manually coro-simple to GLOBAL_GUARDS and then 
177 #   rerun the patches/make/each-patch-repo.sh script as earlier
178
179
180 # Finish the setup
181 (cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup")
182 # If this last command failed, check your mercurial config within ~/.hgrc (see above)
183 ~~~~       
184  -# Compile it all
185 ~~~~{.sh}
186 unset LD_LIBRARY_PATH
187 export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
188 cd sources
189 # Check that everything is fine
190 make sanity
191 # Go for it (it takes about half an hour on my machine)
192 make all
193
194 # Check that the coroutine library got compiled in
195 ls sources/build/linux-amd64/classes/java/dyn/
196 # This should display a bunch of class files. If not, something went wrong, you need to investigate further
197 ~~~~
198
199 \subsubsection  bindings_java_coro_use Using coroutine contexts
200
201 SimGrid Java will automatically switch to the coroutine context
202 factory if your JVM support it, so you will just need to execute your
203 simulation with the correct JVM. The selected context factory gets
204 displayed automatically.
205 ~~~~{.sh}
206 export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libSG_java.so
207 cd examples
208 $PATH_TO_COROUTINE_JVM/java -cp .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
209 ~~~~
210
211 Note that you may have to adjust the "coro.stacksPerThread"
212 configuration option to run large simulations. The default is 100 and
213 you want to increase it to run more processes.
214 ~~~~{.sh}
215 $ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
216 ~~~~
217
218 If you reach the point where the creation of new simulated processes
219 fail with the message "Can't create coroutine object", you may need to
220 increase the relevant system limit with the following command.
221 ~~~~{.sh}
222 sysctl -w vm.max_map_count = 131072
223 ~~~~
224
225 The full story is that each coroutine requires two memory maps, and
226 that Linux puts a limit on the total amount of memory maps that each
227 process can manage (by default, this limit is often at 65535). Since
228 the JVM needs a few dozen of such maps on its own (three maps per
229 dynamic library -- check `/proc/the_pid/maps` if you don't believe it),
230 this is enough to create over 30,000 simulated processes. But to go
231 futher, that limit must be modified. 
232
233 If you want to make this change permanent on your machine, edit your
234 `/etc/sysctl.conf` file. Otherwise, you have to redo it by calling
235 sysctl after each reboot.
236
237 \section bindings_binding_lua Lua Binding
238
239 Most of Simgrid modules require a  good level in C programming, since simgrid is used to be as standard C library.
240  Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works,
241  which avoid dealing with C errors, and sometime an important  gain of time.
242 Besides Java Binding, Lua  and Ruby bindings are available since version 3.4 of Simgrid
243 for MSG Module, and we are currenlty working on bindings for other modules.
244
245 \subsection bindings_binding_lua_about What is lua ?
246 Lua is a lightweight, reflective, imperative and functional programming language,
247  designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
248 \subsubsection bindings_binding_lua_why Why lua ?
249 Lua is a fast, portable and powerful script language, quite simple to use for developpers.
250 it combines procedural features with powerful data description facilities,
251  by using a simple, yet powerful, mechanism of tables.
252 Lua has a relatively simple C API compared to other scripting languages,
253 and accordingly it provides a robust, easy to use it.
254 \subsubsection bindings_binding_lua_simgrid How to use lua in Simgrid ?
255 Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :
256   - Coding functions coresponding to each process
257   - loading the platforme/deployment XML file that describe the environment of simulation
258   - and … Running the Simulation.
259
260 \dontinclude lua/masterslave/master.lua
261 \subsection bindings_binding_lua_example_master_slave Master/Slave Example
262
263  \li Master Code
264  \until end_of_master
265 we mainly  use   simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
266          then simgrid.Task.send(task,alias) to send it.
267 we use also simgrid.Task.name(task), to get the task's name.
268
269 \dontinclude lua/masterslave/slave.lua
270 \li Slave Code
271 \until end_of_slave
272 Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias,
273 this function return directly the task recevied.
274
275 \dontinclude lua/masterslave/master_slave.lua
276 \li Set Environmenet and run application
277 \until end-of-master-slave
278
279 \subsection bindings_binding_lua_example_data Exchanging Data
280 You can also exchange data between Process using lua. for that, you have to deal with lua task as a table,
281 since lua is based itself on a mechanism of tables,
282 so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
283
284 \li Sender process
285 \verbatim
286   task = simgrid.Task.new("data_task",task_comp,task_comm);
287   task['matrix'] = my_matrix;
288   task['table'] = my_table;
289   task['message'] = "Hello from (Lua || Simgrid ) !! "
290   …
291   simgrid.Task.send(task,alias)
292 \endverbatim
293         After creating task, we associate to it various kind of data with a specific key (string in this case)
294         to distinguish between data variables. The receiver will use this key to access easily to datas.
295
296
297 \li Receiver processe
298 \verbatim
299   task = simgrid.Task.recv(alias);
300   sender_matrix = task['matrix'];
301   sender_table = task['table'];
302   sender_message = task['message']
303   ...
304 \endverbatim
305         Note that in lua, both sender and receiver share the same lua task.
306         So that the receiver could joint data directly on the received task without sending it back.
307         You can find  a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
308
309
310 \subsection bindings_binding_lua_example_bypass Bypass XML
311         maybe you wonder if there is a way to bypass the XML files,
312          and describe your platform directly from the code, with lua bindings it's Possible !! how ?
313         We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
314      ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
315
316
317 \li set Routing mode
318 \verbatim
319    simgrid.AS.new{id="AS0",mode="Full"};
320 \endverbatim
321
322 \li set Hosts
323 \verbatim
324   simgrid.Host.new{id="Tremblay",power=98095000};
325   simgrid.Host.new{id="Jupiter",power=76296000};
326   simgrid.Host.new{id="Fafard",power=76296000};
327   simgrid.Host.new{id="Ginette",power=48492000};
328   simgrid.Host.new{id="Bourassa",power=48492000};
329 \endverbatim
330   we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
331
332 \li set Links
333 \verbatim
334   for i=0,11 do
335     simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087};    --  some crazy values ;)
336   end
337 \endverbatim
338   we used simgrid.Link.new{id=link_id,bandwidth=bw,latency=lat} with a simple for loop to create all links we need (much easier than XML hein ?)
339
340 \li set Routes
341 \verbatim
342 -- simgrid.Route.new(src_id,des_id,links_nb,links_list)
343    simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
344    simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
345    simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
346    simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
347
348    simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
349    simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
350    simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
351    simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
352    ...
353 \endverbatim
354   for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
355
356 \li Save platform
357 \verbatim
358   simgrid.register_platform();
359 \endverbatim
360 Don't forget to register your platform, that SURF callbacks starts their work ;)
361
362 \li set application
363 \verbatim
364    simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
365    simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
366    simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
367    simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
368    simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
369 \endverbatim
370   you don't  need to use a deployment XML file, thanks to  simgrid.Host.setFunction(host_id,function,args_number,args_list)
371   you can associate functions for each host with arguments if needed .
372
373 \li
374 \verbatim
375    simgrid.register_application();
376 \endverbatim
377 Yes, Here too you have to register your application before running the simulation.
378
379 the full example is distributed in the file examples/lua/master_slave_bypass.lua
380
381 \subsection MSG_ex_master_slave_lua Master/slave Lua application
382
383 Simulation of a master-slave application using lua bindings    
384 - \ref MSG_ext_ms_master_lua
385 - \ref MSG_ext_ms_slave_lua
386 - \ref MSG_ext_ms_core_lua
387 - \ref MSG_ext_ms_helping
388 - \ref MSG_ext_ms_application
389 - \ref MSG_ext_ms_platform
390
391
392      
393 \subsubsection MSG_ext_ms_master_lua Master code
394
395 as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master.
396
397 Lua style arguments (...) in for the master are interpreted as:
398 - the number of tasks to distribute
399 - the computation size of each task
400 - the size of the files associated to each task
401 - a list of host that will accept those tasks.
402
403 Tasks are dumbly sent in a round-robin style.
404 \dontinclude lua/masterslave/master.lua
405 \skip Dispatch the tasks
406 \until Done sending
407 \until end
408
409
410 \subsubsection MSG_ext_ms_slave_lua Slave code
411
412 This function has to be assigned to a #msg_process_t that has to behave as a slave.
413 This function keeps waiting for tasks and executes them as it receives them.
414 \dontinclude lua/masterslave/slave.lua
415 \until end_of_slave
416 \subsubsection MSG_ext_ms_core_lua Simulation core
417
418 in this section the core of the simulation which start by including the simgrid lib for bindings
419 : <i>require "simgrid" </i>
420
421 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
422    environment
423 -# Application deployment : create the processes on the right locations with
424     <i>simgrid.application</i>
425 -# The simulation is run with <i>simgrid.run</i>
426
427 Its arguments are:
428 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
429 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
430 \dontinclude lua/masterslave/master_slave.lua
431 \skip platform
432 \until run
433
434
435 \subsection MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
436
437 Simulation of a master-slave application using lua bindings, Bypassing the XML parser
438 - \ref MSG_ext_ms_bp_master_lua
439 - \ref MSG_ext_ms_bp_slave_lua
440 - \ref MSG_ext_ms_bp_core_lua
441
442       
443
444 \subsubsection MSG_ext_ms_bp_master_lua Master code
445
446 as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master.
447
448 Lua style arguments (...) in for the master are interpreted as:
449 - the number of tasks to distribute
450 - the computation size of each task
451 - the size of the files associated to each task
452 - a list of host that will accept those tasks.
453
454 Tasks are dumbly sent in a round-robin style.
455
456 \dontinclude lua/console/master.lua
457 \until end_of_master
458
459 \subsubsection MSG_ext_ms_bp_slave_lua Slave code
460
461 This function has to be assigned to a #msg_process_t that has to behave as a slave.
462 This function keeps waiting for tasks and executes them as it receives them.
463
464 \dontinclude lua/console/slave.lua
465 \until end_of_slave
466
467 \subsubsection MSG_ext_ms_bp_core_lua Simulation core
468
469 in this section the core of the simulation which start by including the simgrid lib for bindings, then create the resources we need to set up our environment bypassing the XML parser.
470 : <i>require "simgrid" </i>
471
472 -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
473 -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
474 -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
475 -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
476
477 we can also bypass the XML deployment file, and associate functions for each of defined hosts.
478 - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
479 - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
480
481 \include lua/console/master_slave_bypass.lua
482
483
484  */