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