How to install the Java bindings

This is documented in the Build the Java bindings Section.

How to use the Java bindings

In most cases, you can use the SimGrid bindings as if it was a Java library:

$ 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:

$ 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 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.

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).

$ 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.

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.

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.

Getting a mlvm JVM

You need to get a patched JVM from here (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
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
# 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
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

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.

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.

$ $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.

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.