1 /*! @page MSG_Java Java Bindings
5 This section describes jMSG, the Java API to Simgrid. This API mimicks
6 @ref MSG_API "MSG", which is a simple yet somehow realistic interface.
7 <b>The full [javadoc](javadoc/index.html) is available.</b>
9 Most of the documentation of the @ref MSG_API "MSG API" in C applies
10 directly to the Java bindings (any divergence is seen as a bug that we
11 should fix). MSG structures are mapped to Java objects as expected,
12 and the MSG functions are methods in these objects.
14 @section java_install How to install the Java bindings
16 This is documented in the @ref install_java Section.
18 @section java_use How to use the Java bindings
20 In most cases, you can use the SimGrid bindings as if it was a Java
24 $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
25 $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
31 $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml
34 Any SimGrid simulation (java or not) is usually constituted of several
35 kind of actors or processes (classes extending @c Msg.Process) that
36 are deployed over the hosts of the virtual platform. So, your code
37 should declare these actors, plus a Main class in charge of deploying
38 your actors on the platform. Please refer to the examples for details.
40 @subsection java_use_trouble Troubleshooting
42 Actually, these bindings are not only implemented in Java. They do use
43 the C implementation of SimGrid. This should be transparent as this
44 library is directly included in the `simgrid.jar` file but things can
45 still go wrong is several ways.
47 ** **Error: library simgrid not found**
49 This means that the JVM fails to load the native library. You should
50 try to rebuild the simgrid.jar file as explained above. If it does not
51 help, you can try to use an installed version of the library instead
52 of the one included in the jar. For that, specify the path to the
53 native library in the `LD_LIBRARY_PATH` variable (or in the
54 `DYLD_LIBRARY_PATH` on Mac OSX).
57 $ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
58 $ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
61 Add these lines to your `~/.bashrc` file or equivalent to make these
62 settings permanent even after a reboot.
64 ** **pthread_create failed**
66 You reached the amount of threads that can be run on your system. Try
67 increasing the thread limits of your operating system.
69 If you manage to get it working, you could also switch to the Java
70 co-routines (see @ref bindings_java_coro_install). Unfortunately,
71 nobody used them since a few years, so they may well be broken by now.
75 When using jMSG, your program can crash for 3 main reasons:
76 - Your Java part is not good: you'll have a good old java exception thrown,
77 and hence you should be able to correct it by yourself.
78 - Our java part is not good: you'll also have a java exception thrown, but
79 we have real doubts this can happen, since the java part is only a JNI
80 binding. The other option is that it crashed because you used incorrectly
81 the MSG API, so this means also you should have an MSGException. It means
82 you should read carefully MSG samples and/or documentation.
83 - Something has crashed in the C part. Okay, here comes the tricky
84 thing. It happens mainly for 2 reasons:
85 - When something goes wrong in your simulation, sometimes the C part stops
86 because you used SimGrid incorrectly, and JNI bindings are not fond of that.
87 It means that you'll have something that looks ugly, but you should be able
88 to identify what's going wrong in your code by carefully reading the whole
90 - It may happen that the problem comes directly from SimGrid: in this case,
91 the error should be uglier. In that case, you may submit a bug directly to
94 @section java_coroutines Java bindings on Steroids
96 <b>THIS SECTION IS SOMEWHAT OBSOLETE</b> because building a JVM
97 providing coroutines is probably not possible anymore nowadays. If you
98 really need performance for your Java simulation, please contact us.
100 There is two main motivations to use the coroutine variant of SimGrid
101 Java bindings: it's about 5 times faster than the default thread-based
102 context factory, and the amount of runnable processes is then only
103 limited by the amount of RAM that you have. The drawbacks are that it
104 requires a specific and rather experimental JVM to run, and that this
105 context factory itself remains a bit experimental so far.
107 @subsection bindings_java_coro_install Getting a mlvm JVM
109 You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/)
110 (many thanks to Lukas Stadler for this work!).
112 You can either get a prebuilt binary, or recompile your own JVM. Make
113 sure to get a coro-simple version, as we don't need to serialize nor
114 migrate stacks in SimGrid. You should be able to follow the `README.txt`
115 that you'll get in the repository, but here is how we did it, just in
116 case. The instructions are given for a debian or Ubuntu box, but I
117 think you should manage to convert it to your system quite easily.
118 Finally, if you're really stuck, you can get the version compiled by
119 Jonathan Rouzaud-Cornabas from his web page. This version is known to
120 work with SimGrid for sure!
121 http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
123 -# Install mercurial and some dependencies
125 sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
126 # Grab the forest extension: we need to source-install it
127 hg clone https://bitbucket.org/gxti/hgforest hgforest
129 -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
130 following lines. Don't forget to change the /path/to/forest.py to
131 point to where you just downloaded the source.
133 Forest extension is needed to download the openjdk source code and
134 patches while the mq line is needed to apply the patches. The
135 username is needed at the step "preparing the sources", not sure why.
138 username = YouUserameWithoutSpaces
140 forest=/path/to/forest.py
143 -# Prepare the source code
145 # create a working directory, and enter it
146 mkdir davinci; cd davinci
149 hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
151 hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
153 # Link the patch directories into the sources
154 bash patches/make/link-patch-dirs.sh sources patches
155 # Test wether the previous command worked with
156 ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
157 # It should display something like the following.
158 # (note that both file share the same inode number)
159 # 9707849 patches/hotspot/series
160 # 9707849 sources/hotspot/.hg/patches/series
162 # Specify what to compile.
163 export davinci=${pwd} guards="buildable testable coro-simple"
165 sh patches/make/each-patch-repo.sh hg qselect --reapply $guards `sh $davinci/patches/make/current-release.sh`
166 # Check that it understood that you want the patch applied:
167 grep -r GLOBAL_GUARDS patches/make/
168 # this should display something like the following (maybe amonst other unrelated lines)
169 # GLOBAL_GUARDS=buildable testable coro-simple
170 # If this does not work, edit patches/make/Makefile,
171 # manually coro-simple to GLOBAL_GUARDS and then
172 # rerun the patches/make/each-patch-repo.sh script as earlier
177 make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup"
178 # If this last command failed, check your mercurial config within ~/.hgrc (see above)
182 unset LD_LIBRARY_PATH
183 export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
185 # Check that everything is fine
187 # Go for it (it takes about half an hour on my machine)
190 # Check that the coroutine library got compiled in
191 ls sources/build/linux-amd64/classes/java/dyn/
192 # This should display a bunch of class files. If not, something went wrong, you need to investigate further
195 @subsection bindings_java_coro_use Using coroutine contexts
197 SimGrid Java will automatically switch to the coroutine context
198 factory if your JVM support it, so you will just need to execute your
199 simulation with the correct JVM. The selected context factory gets
200 displayed automatically.
202 export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so
204 $PATH_TO_COROUTINE_JVM/java -classpath .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
207 Note that you may have to adjust the "coro.stacksPerThread"
208 configuration option to run large simulations. The default is 100 and
209 you want to increase it to run more processes.
211 $ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
214 If you reach the point where the creation of new simulated processes
215 fail with the message "Can't create coroutine object", you may need to
216 increase the relevant system limit with the following command.
218 sysctl -w vm.max_map_count = 131072
221 The full story is that each coroutine requires two memory maps, and
222 that Linux puts a limit on the total amount of memory maps that each
223 process can manage (by default, this limit is often at 65535). Since
224 the JVM needs a few dozen of such maps on its own (three maps per
225 dynamic library -- check `/proc/the_pid/maps` if you don't believe it),
226 this is enough to create over 30,000 simulated processes. But to go
227 futher, that limit must be modified.
229 If you want to make this change permanent on your machine, edit your
230 `/etc/sysctl.conf` file. Otherwise, you have to redo it by calling
231 sysctl after each reboot.