X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7a8cd62135619ad52e05ae1c929ef07e166e4260..2e9105988280d1e88b5b496d6e2eed4c8d541883:/doc/doxygen/bindings.doc diff --git a/doc/doxygen/bindings.doc b/doc/doxygen/bindings.doc index aec7344789..0a8cbbdb3a 100644 --- a/doc/doxygen/bindings.doc +++ b/doc/doxygen/bindings.doc @@ -1,11 +1,238 @@ /*! \page bindings Bindings +\section bindings_binding_Ruby Ruby Binding +Check online for our specific [Simgrid-Ruby documentation](http://simgrid.gforge.inria.fr/documentation.html). \section bindings_binding_Java Java Binding -Check online for our specific Simgrid-Java documentation. - -\section bindings_binding_Ruby Ruby Binding -Check online for our specific Simgrid-Ruby documentation. +Simgrid-java is a java API that let you use [Simgrid](http://simgrid.gforge.inria.fr/) +MSG API in your favorite language (java). Without it, you would be forced to +use C or one of the other bindings provided. + +MSG was the first distributed programming environment provided within SimGrid. +While almost realistic, it remains quite simple. This describes the Java +bindings to this interface. + +The javadoc is accessible [here](javadoc/index.html) + +\subsection bindings_binding_Java_jMSG_who Who should use this (and who shouldn't) +You should use MSG if you want to study some heuristics for a given problem you +don't really want to implement. SimGrid-java let you use MSG while coding in +Java. So if your need is MSG + Java, you're in the right section! + +\subsection SimGrid-java Usage overview + +To make a long story short, it's a JNI binding, so it implies that: +- Most of the MSG and SimGrid documentation about behavioral aspects applies + directly to what you are programming. +- MSG data structures are mapped to Java objects. So it means that from the + syntax point of view, you have to know how those objects are. Fortunately, + we have generated the Javadoc for those objects. So take a look at it + +Finally, it implies also that your program can crash for 3 main reasons: +- Your Java part is not good: you'll have a good old java exception thrown, + and hence you should be able to correct it by yourself. +- Our java part is not good: you'll also have a java exception thrown, but + we have real doubts this can happen, since the java part is only a JNI + binding. The other option is that it crashed because you used incorrectly + the MSG API, so this means also you should have an MSGException. It means + you should read carefully MSG samples and/or documentation. +- Something has crashed in the C part. Okay, here comes the tricky thing. + +C crashes mainly for 2 reasons: +- When something goes wrong in your simulation, sometimes the C part stops + because you used SimGrid incorrectly, and JNI bindings are not fond of that. + It means that you'll have something that looks ugly, but you should be able + to identify what's going wrong in your code by carefully reading the whole + error message +- It may happen that the problem comes directly from SimGrid: in this case, + the error should be uglier. In that case, you may submit a bug directly to + SimGrid. + +\subsection bindings_binding_java_install How to install Simgrid-java + +To use java with Simgrid you have to install some dependencies: +- Java JDK packages, such as `openjdk7` or `sun-java6-jdk` (with `libgcj10-dev` or another + version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see + \ref bindings_binding_java_coroutines). + +Then build Simgrid with the Java bindings enabled: +~~~~{.sh} +cmake -Denable_java=ON . +~~~~ + +If cmake complains that **jni could not be found**, you need to tell it where +JNI header files are located. the following command should tell you: + +~~~~{.sh} +$ locate jni.h +/usr/lib/jvm/java-6-openjdk-amd64/include/jni.h +/usr/lib/jvm/java-7-openjdk-amd64/include/jni.h +~~~~ + +If you have several version of jni installed (as in the example +above), you need to check the version of java that is used by default +on your machine (using javac -version), and pick the right one. Then +set the `JAVA_INCLUDE_PATH` environment variable to the right path (note +that we remove the filename `jni.h` from that path), and relaunch cmake. + +~~~~{.sh} +$ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/ +$ cmake . +~~~~ + +\subsubsection bindings_binding_java_use How to use Simgrid-java + +To execute the examples you need to add the path where you installed +the generated `libSG_java` and `libsimgrid` libraries +into the `LD_LIBRARY_PATH`. + +Be careful on Mac, this variable is called `DYLD_LIBRARY_PATH` and not +`LD_LIBRARY_PATH`. + +~~~~{.sh} +$ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library +$ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib +$ cd examples +$ java -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml +~~~~ + +If you want to make these settings permanent even after a reboot, you +need to add the export lines into your `~/.bashrc` file, or equivalent. + +\subsubsection bindings_binding_java_coroutines How to use the coroutines context factory + +There is two main motivations to use the coroutine variant of SimGrid +Java bindings: it's about 5 times faster than the default thread-based +context factory, and the amount of runnable processes is then only +limited by the amount of RAM that you have. The drawbacks are that it +requires a specific and rather experimental JVM to run, and that this +context factory itself remains a bit experimental so far. + +\subsubsection bindings_java_coro_install Getting a mlvm JVM + +You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/) +(many thanks to Lukas Stadler for this work!). + +You can either get a prebuilt binary, or recompile your own JVM. Make +sure to get a coro-simple version, as we don't need to serialize nor +migrate stacks in SimGrid. You should be able to follow the `README.txt` +that you'll get in the repository, but here is how we did it, just in +case. The instructions are given for a debian or Ubuntu box, but I +think you should manage to convert it to your system quite easily. +Finally, if you're really stuck, you can get the version compiled by +Jonathan Rouzaud-Cornabas from his web page. This version is known to +work with SimGrid for sure! +http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz + + -# Install mercurial and some dependencies +~~~~{.sh} +sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev +# Grab the forest extension: we need to source-install it +hg clone https://bitbucket.org/gxti/hgforest hgforest \endverbatim +~~~~ + -# Configure the mercurial extensions: Edit ~/.hgrc and paste the + following lines. Don't forget to change the /path/to/forest.py to + point to where you just downloaded the source. + + Forest extension is needed to download the openjdk source code and + patches while the mq line is needed to apply the patches. The + username is needed at the step "preparing the sources", not sure why. +~~~~ +[ui] +username = YouUserameWithoutSpaces +[extensions] +forest=/path/to/forest.py +mq= +~~~~ + -# Prepare the source code +~~~~{.sh} +# create a working directory, and enter it +mkdir davinci; cd davinci + +# Grab the sources +hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources +# Grab the patches +hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches + +# Link the patch directories into the sources +bash patches/make/link-patch-dirs.sh sources patches +# Test wether the previous command worked with +ls -i patches/hotspot/series sources/hotspot/.hg/patches/series +# It should display something like the following. +# (note that both file share the same inode number) +# 9707849 patches/hotspot/series +# 9707849 sources/hotspot/.hg/patches/series + + +# Specify what to compile. +export davinci=$(pwd) guards="buildable testable coro-simple" +# Apply the patches +sh patches/make/each-patch-repo.sh hg qselect --reapply $guards '$(sh $davinci/patches/make/current-release.sh)' +# Check that it understood that you want the patch applied: +grep GLOBAL_GUARDS patches/make/* -r +# this should display something like the following (maybe amonst other unrelated lines) +# GLOBAL_GUARDS=buildable testable coro-simple +# If this does not work, edit patches/make/Makefile, +# manually coro-simple to GLOBAL_GUARDS and then +# rerun the patches/make/each-patch-repo.sh script as earlier + + +# Finish the setup +(cd patches/make; make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup") +# If this last command failed, check your mercurial config within ~/.hgrc (see above) +~~~~ + -# Compile it all +~~~~{.sh} +unset LD_LIBRARY_PATH +export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/ +cd sources +# Check that everything is fine +make sanity +# Go for it (it takes about half an hour on my machine) +make all + +# Check that the coroutine library got compiled in +ls sources/build/linux-amd64/classes/java/dyn/ +# This should display a bunch of class files. If not, something went wrong, you need to investigate further +~~~~ + +\subsubsection bindings_java_coro_use Using coroutine contexts + +SimGrid Java will automatically switch to the coroutine context +factory if your JVM support it, so you will just need to execute your +simulation with the correct JVM. The selected context factory gets +displayed automatically. +~~~~{.sh} +export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libSG_java.so +cd examples +$PATH_TO_COROUTINE_JVM/java -cp .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml +~~~~ + +Note that you may have to adjust the "coro.stacksPerThread" +configuration option to run large simulations. The default is 100 and +you want to increase it to run more processes. +~~~~{.sh} +$ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -cp .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml +~~~~ + +If you reach the point where the creation of new simulated processes +fail with the message "Can't create coroutine object", you may need to +increase the relevant system limit with the following command. +~~~~{.sh} +sysctl -w vm.max_map_count = 131072 +~~~~ + +The full story is that each coroutine requires two memory maps, and +that Linux puts a limit on the total amount of memory maps that each +process can manage (by default, this limit is often at 65535). Since +the JVM needs a few dozen of such maps on its own (three maps per +dynamic library -- check `/proc/the_pid/maps` if you don't believe it), +this is enough to create over 30,000 simulated processes. But to go +futher, that limit must be modified. + +If you want to make this change permanent on your machine, edit your +`/etc/sysctl.conf` file. Otherwise, you have to redo it by calling +sysctl after each reboot. \section bindings_binding_lua Lua Binding @@ -15,7 +242,6 @@ Most of Simgrid modules require a good level in C programming, since simgrid is Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid for MSG Module, and we are currenlty working on bindings for other modules. - \subsection bindings_binding_lua_about What is lua ? Lua is a lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal (see official web site here).