X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/b7c3da37d0776e2e3daadc7ea96dffdee4e809a4..f04cb933da95f9df2da6d58a72a7b1da12582f7d:/doc/doxygen/java.doc diff --git a/doc/doxygen/java.doc b/doc/doxygen/java.doc deleted file mode 100644 index d4c273adcf..0000000000 --- a/doc/doxygen/java.doc +++ /dev/null @@ -1,233 +0,0 @@ -/*! @page MSG_Java Java Bindings - -@tableofcontents - -This section describes jMSG, the Java API to Simgrid. This API mimicks -@ref MSG_API "MSG", which is a simple yet somehow realistic interface. -The full [javadoc](javadoc/index.html) is available. - -Most of the documentation of the @ref MSG_API "MSG API" in C applies -directly to the Java bindings (any divergence is seen as a bug that we -should fix). MSG structures are mapped to Java objects as expected, -and the MSG functions are methods in these objects. - -@section java_install How to install the Java bindings - -This is documented in the @ref install_java Section. - -@section java_use How to use the Java bindings - -In most cases, you can use the SimGrid bindings as if it was a Java -library: - -~~~~{.sh} -$ javac -classpath .:path/to/simgrid.jar your/java/Code.java -$ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code -~~~~ - -For example: -~~~~{.sh} -$ cd examples/java -$ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml -~~~~ - -Any SimGrid simulation (java or not) is usually constituted of several -kind of actors or processes (classes extending @c Msg.Process) that -are deployed over the hosts of the virtual platform. So, your code -should declare these actors, plus a Main class in charge of deploying -your actors on the platform. Please refer to the examples for details. - -@subsection java_use_trouble Troubleshooting - -Actually, these bindings are not only implemented in Java. They do use -the C implementation of SimGrid. This should be transparent as this -library is directly included in the `simgrid.jar` file but things can -still go wrong is several ways. - -** **Error: library simgrid not found** - -This means that the JVM fails to load the native library. You should -try to rebuild the simgrid.jar file as explained above. If it does not -help, you can try to use an installed version of the library instead -of the one included in the jar. For that, specify the path to the -native library in the `LD_LIBRARY_PATH` variable (or in the -`DYLD_LIBRARY_PATH` on Mac OSX). - -~~~~{.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 -~~~~ - -Add these lines to your `~/.bashrc` file or equivalent to make these -settings permanent even after a reboot. - -** **pthread_create failed** - -You reached the amount of threads that can be run on your system. Try -increasing the thread limits of your operating system. - -If you manage to get it working, you could also switch to the Java -co-routines (see @ref bindings_java_coro_install). Unfortunately, -nobody used them since a few years, so they may well be broken by now. - -** **Other errors** - -When using jMSG, 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. It happens 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. - -@section java_coroutines Java bindings on Steroids - -THIS SECTION IS SOMEWHAT OBSOLETE because building a JVM -providing coroutines is probably not possible anymore nowadays. If you -really need performance for your Java simulation, please contact us. - -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. - -@subsection 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 -~~~~ - -# 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 -r GLOBAL_GUARDS patches/make/ -# 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 -~~~~ - -@subsection 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/libsimgrid-java.so -cd examples -$PATH_TO_COROUTINE_JVM/java -classpath .:../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 -classpath .:../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. - - */