docs/source/app_java.rst

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