docs/source/app_java.rst

   1 .. _Java_doc:
   2
   3 =================
   4 The Java Bindings
   5 =================
   6
   7 .. raw:: html
   8
   9    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
  10    <script>
  11    window.onload=function() { // Wait for the SVG to be loaded before changing it
  12      //var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
  13      //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
  14    }
  15    </script>
  16    <br/>
  17    <br/>
  18
  19
  20 This section describes jMSG, the Java API to Simgrid. This API mimicks
  21 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
  22 <b>The full [javadoc](javadoc/index.html) is available.</b>
  23
  24 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
  25 directly to the Java bindings (any divergence is seen as a bug that we
  26 should fix). MSG structures are mapped to Java objects as expected,
  27 and the MSG functions are methods in these objects.
  28
  29 How to install the Java bindings
  30 --------------------------------
  31
  32 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
  33 but some people may prefer to :ref:`compile it from the sources <install_src>`.
  34
  35
  36 How to use the Java bindings
  37 ----------------------------
  38
  39 In most cases, you can use the SimGrid bindings as if it was a Java
  40 library:
  41
  42 .. code-block:: shell
  43
  44    $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
  45    $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
  46
  47 For example:
  48
  49 .. code-block:: shell
  50
  51    $ cd examples/java
  52    $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml
  53
  54 Any SimGrid simulation (java or not) is usually constituted of several
  55 kind of actors or processes (classes extending @c Msg.Process) that
  56 are deployed over the hosts of the virtual platform. So, your code
  57 should declare these actors, plus a Main class in charge of deploying
  58 your actors on the platform. Please refer to the examples for details.
  59
  60 Troubleshooting
  61 ---------------
  62
  63 Actually, these bindings are not only implemented in Java. They do use
  64 the C implementation of SimGrid. This should be transparent as this
  65 library is directly included in the ``simgrid.jar`` file but things can
  66 still go wrong is several ways.
  67
  68 Error: library simgrid not found
  69 ................................
  70
  71 This means that the JVM fails to load the native library. If you use a
  72 precompiled jarfile, please report this bug.
  73
  74 If you built it yourself, you can try to use an installed version of
  75 the library instead of the one included in the jar. For that, add the
  76 path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
  77 the ``DYLD_LIBRARY_PATH`` on Mac OSX).
  78
  79 pthread_create failed
  80 .....................
  81
  82 You reached the amount of threads that can be run on your system. Try
  83 increasing the thread limits of your operating system.
  84
  85 Other errors
  86 ............
  87
  88 When using jMSG, your program can crash for 3 main reasons:
  89
  90 - Your Java part is not good: you'll have a good old java exception thrown,
  91   and hence you should be able to correct it by yourself.
  92 - Our java part is not good: you'll also have a java exception thrown, but
  93   we have real doubts this can happen, since the java part is only a JNI
  94   binding. The other option is that it crashed because you used incorrectly
  95   the MSG API, so this means also you should have an MSGException. It means
  96   you should read carefully MSG samples and/or documentation.
  97 - Something has crashed in the C part. Okay, here comes the tricky
  98   thing. It happens mainly for 2 reasons:
  99
 100   - When something goes wrong in your simulation, sometimes the C part stops
 101     because you used SimGrid incorrectly, and JNI bindings are not fond of that.
 102     It means that you'll have something that looks ugly, but you should be able
 103     to identify what's going wrong in your code by carefully reading the whole
 104     error message
 105   - It may happen that the problem comes directly from SimGrid: in this case,
 106     the error should be uglier. In that case, you may submit a bug directly to
 107     SimGrid.
 108