+++ /dev/null
-/*! @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.
-<b>The full [javadoc](javadoc/index.html) is available.</b>
-
-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
-
-<b>THIS SECTION IS SOMEWHAT OBSOLETE</b> 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.
-
- */
