Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Move MSG and SimDag examples out of the sight of users
[simgrid.git] / 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>