doc/doxygen/java.doc

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