doc/doxygen/java.doc

   1 /*! \page bindings Bindings
   2
   3 \section MSG_Java Java Binding
   4 Simgrid-java is a java API that let you use [Simgrid](http://simgrid.gforge.inria.fr/)
   5 MSG and SURF API in your favorite language (java). Without it, you would be forced to
   6 use C or one of the other bindings provided.
   7
   8 MSG was the first distributed programming environment provided within SimGrid.
   9 While almost realistic, it remains quite simple. This describes the Java
  10 bindings to this interface.
  11
  12 The javadoc is accessible [here](javadoc/index.html)
  13
  14 \subsection bindings_binding_Java_jMSG_who Who should use this (and who shouldn't)
  15 You should use MSG if you want to study some heuristics for a given problem you
  16 don't really want to implement. SimGrid-java let you use MSG and SURF while coding in
  17 Java. So if your need is MSG + Java (+ SURF), you're in the right section!
  18
  19 \subsection SimGrid-java Usage overview
  20
  21 To make a long story short, it's a JNI binding for MSG and a SWIG binding for SURF,
  22 so it implies that:
  23 - Most of the MSG/SURF and SimGrid documentation about behavioral aspects applies
  24   directly to what you are programming.
  25 - MSG/SURF data structures are mapped to Java objects. So it means that from the
  26   syntax point of view, you have to know how those objects are. Fortunately,
  27   we have generated the Javadoc for those objects. So take a look at it
  28
  29 Finally, it implies also that your program can crash for 3 main reasons:
  30 - Your Java part is not good: you'll have a good old java exception thrown,
  31   and hence you should be able to correct it by yourself.
  32 - Our java part is not good: you'll also have a java exception thrown, but
  33   we have real doubts this can happen, since the java part is only a JNI
  34   binding. The other option is that it crashed because you used incorrectly
  35   the MSG API, so this means also you should have an MSGException. It means
  36   you should read carefully MSG samples and/or documentation.
  37 - Something has crashed in the C part. Okay, here comes the tricky thing.
  38
  39 C crashes mainly for 2 reasons:
  40 - When something goes wrong in your simulation, sometimes the C part stops
  41   because you used SimGrid incorrectly, and JNI bindings are not fond of that.
  42   It means that you'll have something that looks ugly, but you should be able
  43   to identify what's going wrong in your code by carefully reading the whole
  44   error message
  45 - It may happen that the problem comes directly from SimGrid: in this case,
  46   the error should be uglier. In that case, you may submit a bug directly to
  47   SimGrid.
  48
  49 \subsection bindings_binding_java_install How to install Simgrid-java
  50
  51 To use java with Simgrid you have to install some dependencies:
  52 - Java JDK packages, such as `openjdk7` or `sun-java6-jdk` (with `libgcj10-dev` or another
  53   version of gcj). For maximal performance and scalability, use a coroutine-enabled JVM (see
  54   \ref bindings_binding_java_coroutines).
  55
  56 Then build Simgrid with the Java bindings enabled:
  57 ~~~~{.sh}
  58 cmake -Denable_java=ON .
  59 ~~~~
  60
  61 If cmake complains that **jni could not be found**, you need to tell it where
  62 JNI header files are located. the following command should tell you:
  63
  64 ~~~~{.sh}
  65 $ locate jni.h
  66 /usr/lib/jvm/java-6-openjdk-amd64/include/jni.h
  67 /usr/lib/jvm/java-7-openjdk-amd64/include/jni.h
  68 ~~~~
  69
  70 If you have several version of jni installed (as in the example
  71 above), you need to check the version of java that is used by default
  72 on your machine (using javac -version), and pick the right one. Then
  73 set the `JAVA_INCLUDE_PATH` environment variable to the right path (note
  74 that we remove the filename `jni.h` from that path), and relaunch cmake.
  75
  76 ~~~~{.sh}
  77 $ export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-6-openjdk-amd64/include/
  78 $ cmake .
  79 ~~~~
  80
  81 \subsubsection bindings_binding_java_use How to use Simgrid-java
  82
  83 To execute the examples you need to add the path where you installed
  84 the generated `libsimgrid-java` and `libsimgrid` libraries
  85 into the `LD_LIBRARY_PATH`.
  86
  87 Be careful on Mac, this variable is called `DYLD_LIBRARY_PATH` and not
  88 `LD_LIBRARY_PATH`.
  89
  90 ~~~~{.sh}
  91 $ export SIMGRID_ROOT="$HOME/Install/simgrid/" # change it to the path where you installed the SimGrid library
  92 $ export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$SIMGRID_ROOT/lib
  93 $ cd examples
  94 $ java -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
  95 ~~~~
  96
  97 If you want to make these settings permanent even after a reboot, you
  98 need to add the export lines into your `~/.bashrc` file, or equivalent.
  99
 100 \subsubsection bindings_binding_java_coroutines How to use the coroutines context factory
 101
 102 There is two main motivations to use the coroutine variant of SimGrid
 103 Java bindings: it's about 5 times faster than the default thread-based
 104 context factory, and the amount of runnable processes is then only
 105 limited by the amount of RAM that you have. The drawbacks are that it
 106 requires a specific and rather experimental JVM to run, and that this
 107 context factory itself remains a bit experimental so far.
 108
 109 \subsubsection  bindings_java_coro_install Getting a mlvm JVM
 110
 111 You need to get a patched JVM from [here](http://ssw.jku.at/General/Staff/LS/coro/)
 112 (many thanks to Lukas Stadler for this work!).
 113
 114 You can either get a prebuilt binary, or recompile your own JVM. Make
 115 sure to get a coro-simple version, as we don't need to serialize nor
 116 migrate stacks in SimGrid. You should be able to follow the `README.txt`
 117 that you'll get in the repository, but here is how we did it, just in
 118 case. The instructions are given for a debian or Ubuntu box, but I
 119 think you should manage to convert it to your system quite easily.
 120 Finally, if you're really stuck, you can get the version compiled by
 121 Jonathan Rouzaud-Cornabas from his web page. This version is known to
 122 work with SimGrid for sure!
 123 http://graal.ens-lyon.fr/~jrouzaud/files/corosimple-linux-amd64-20120914.tgz
 124
 125  -# Install mercurial and some dependencies
 126 ~~~~{.sh}
 127 sudo apt-get install mercurial ksh libfreetype6-dev libcups2-dev libasound2-dev gawk openjdk-7-jdk libxext-dev libxrender-dev libxtst-dev
 128 # Grab the forest extension: we need to source-install it
 129 hg clone https://bitbucket.org/gxti/hgforest hgforest
 130 ~~~~
 131  -# Configure the mercurial extensions: Edit ~/.hgrc and paste the
 132     following lines. Don't forget to change the /path/to/forest.py to
 133     point to where you just downloaded the source.
 134
 135     Forest extension is needed to download the openjdk source code and
 136     patches while the mq line is needed to apply the patches. The
 137     username is needed at the step "preparing the sources", not sure why.
 138 ~~~~
 139 [ui]
 140 username = YouUserameWithoutSpaces
 141 [extensions]
 142 forest=/path/to/forest.py
 143 mq=
 144 ~~~~
 145  -# Prepare the source code
 146 ~~~~{.sh}
 147 # create a working directory, and enter it
 148 mkdir davinci; cd davinci
 149
 150 # Grab the sources
 151 hg fclone http://hg.openjdk.java.net/hsx/hotspot-comp sources
 152 # Grab the patches
 153 hg fclone http://hg.openjdk.java.net/mlvm/mlvm patches
 154
 155 # Link the patch directories into the sources
 156 bash patches/make/link-patch-dirs.sh sources patches
 157 # Test wether the previous command worked with
 158 ls -i patches/hotspot/series sources/hotspot/.hg/patches/series
 159 # It should display something like the following.
 160 # (note that both file share the same inode number)
 161 #  9707849 patches/hotspot/series
 162 #  9707849 sources/hotspot/.hg/patches/series
 163
 164 # Specify what to compile.
 165 export davinci=${pwd} guards="buildable testable coro-simple"
 166 # Apply the patches
 167 sh patches/make/each-patch-repo.sh hg qselect --reapply $guards `sh $davinci/patches/make/current-release.sh`
 168 # Check that it understood that you want the patch applied:
 169 grep -r GLOBAL_GUARDS patches/make/
 170 # this should display something like the following (maybe amonst other unrelated lines)
 171 # GLOBAL_GUARDS=buildable testable coro-simple
 172 # If this does not work, edit patches/make/Makefile,
 173 #   manually coro-simple to GLOBAL_GUARDS and then
 174 #   rerun the patches/make/each-patch-repo.sh script as earlier
 175
 176
 177 # Finish the setup
 178 cd patches/make;
 179 make setup && make force && make && make FORCE_VERSIONS=1 && echo "Sources are properly setup"
 180 # If this last command failed, check your mercurial config within ~/.hgrc (see above)
 181 ~~~~
 182  -# Compile it all
 183 ~~~~{.sh}
 184 unset LD_LIBRARY_PATH
 185 export ALT_BOOTDIR=/usr/lib/jvm/java-7-openjdk-amd64/
 186 cd sources
 187 # Check that everything is fine
 188 make sanity
 189 # Go for it (it takes about half an hour on my machine)
 190 make all
 191
 192 # Check that the coroutine library got compiled in
 193 ls sources/build/linux-amd64/classes/java/dyn/
 194 # This should display a bunch of class files. If not, something went wrong, you need to investigate further
 195 ~~~~
 196
 197 \subsubsection  bindings_java_coro_use Using coroutine contexts
 198
 199 SimGrid Java will automatically switch to the coroutine context
 200 factory if your JVM support it, so you will just need to execute your
 201 simulation with the correct JVM. The selected context factory gets
 202 displayed automatically.
 203 ~~~~{.sh}
 204 export LD_LIBRARY_PATH=/path/to/simgrid.so:/path/to/libsimgrid-java.so
 205 cd examples
 206 $PATH_TO_COROUTINE_JVM/java -classpath .:../simgrid.jar masterslave.Masterslave masterslave/ masterslaveDeployment.xml platform.xml
 207 ~~~~
 208
 209 Note that you may have to adjust the "coro.stacksPerThread"
 210 configuration option to run large simulations. The default is 100 and
 211 you want to increase it to run more processes.
 212 ~~~~{.sh}
 213 $ $PATH_TO_COROUTINE_JVM/java -Dcoro.stacksPerThread=$STACKS_NUMBER -classpath .:../simgrid.jar basic/BasicTest platform.xml basic/basicDeployment.xml
 214 ~~~~
 215
 216 If you reach the point where the creation of new simulated processes
 217 fail with the message "Can't create coroutine object", you may need to
 218 increase the relevant system limit with the following command.
 219 ~~~~{.sh}
 220 sysctl -w vm.max_map_count = 131072
 221 ~~~~
 222
 223 The full story is that each coroutine requires two memory maps, and
 224 that Linux puts a limit on the total amount of memory maps that each
 225 process can manage (by default, this limit is often at 65535). Since
 226 the JVM needs a few dozen of such maps on its own (three maps per
 227 dynamic library -- check `/proc/the_pid/maps` if you don't believe it),
 228 this is enough to create over 30,000 simulated processes. But to go
 229 futher, that limit must be modified.
 230
 231 If you want to make this change permanent on your machine, edit your
 232 `/etc/sysctl.conf` file. Otherwise, you have to redo it by calling
 233 sysctl after each reboot.
 234
 235  */