X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/dd96d5146134f3ff468a7835db49556c8e6225a5..a92d60c4f0a9156042fff361f30770e4298fca33:/docs/source/app_msg.rst

diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst
index 04a3514578..23f2fea9d9 100644
--- a/docs/source/app_msg.rst
+++ b/docs/source/app_msg.rst
@@ -1,20 +1,15 @@
 .. _MSG_doc:
 
-====================================
 The MSG Interface (legacy interface)
-====================================
+####################################
 
-.. raw:: html
+.. warning::
 
-   <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
-   <script>
-   window.onload=function() { // Wait for the SVG to be loaded before changing it
-     //var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
-     //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
-   }
-   </script>
-   <br/>
-   <br/>
+   MSG used to be the main API of SimGrid 3, but we are currently in
+   the process of releasing SimGrid 4. So MSG is frozen and will
+   probably never evolve. If you are starting a new project, you
+   should consider S4U instead. Note that the support for MSG will not
+   be removed from SimGrid before 2020 at least.
 
 MSG is a simple API to write algorithms organized with Concurrent
 Sequential Processes (CSP) that interact by exchanging messages. It
@@ -23,19 +18,11 @@ systems. It can be used to build rather realistic simulations, but
 remains simple to use: most unpleasant technical elements can be
 abstracted away rather easily.
 
-This page describes the C version of this API while the :ref:`Java
-bindings of MSG <Java_doc>` are described in another section.
-
-.. warning::
-
-   MSG used to be the main API of SimGrid 3, but we are currently in
-   the process of releasing SimGrid 4. So MSG is frozen and will
-   probably never evolve. If you are starting a new project, you
-   should consider S4U instead. Note that the support for MSG will not
-   be removed from SimGrid before 2020 at least.
+C API reference
+***************
 
 Main MSG Functions
-------------------
+==================
 
 The basic workflow is the following:
 
@@ -59,8 +46,8 @@ The basic workflow is the following:
 .. doxygenfunction:: MSG_main
 .. doxygenfunction:: MSG_set_function
 
-Process Management Functions
-----------------------------
+Process Management
+==================
 
 This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it.
 
@@ -70,7 +57,6 @@ This describes the process structure :cpp:type:`msg_process_t` and the functions
 .. doxygenfunction:: MSG_process_create
 .. doxygenfunction:: MSG_process_create_with_arguments
 .. doxygenfunction:: MSG_process_create_with_environment
-.. doxygenfunction:: MSG_process_create_from_stdfunc
 .. doxygenfunction:: MSG_process_daemonize
 .. doxygenfunction:: MSG_process_detach
 .. doxygenfunction:: MSG_processes_as_dynar
@@ -83,7 +69,6 @@ This describes the process structure :cpp:type:`msg_process_t` and the functions
 .. doxygenfunction:: MSG_process_get_PPID
 .. doxygenfunction:: MSG_process_get_properties
 .. doxygenfunction:: MSG_process_get_property_value
-.. doxygenfunction:: MSG_process_get_smx_ctx
 .. doxygenfunction:: MSG_process_is_suspended
 .. doxygenfunction:: MSG_process_join
 .. doxygenfunction:: MSG_process_kill
@@ -103,10 +88,11 @@ This describes the process structure :cpp:type:`msg_process_t` and the functions
 .. doxygenfunction:: MSG_process_sleep
 .. doxygenfunction:: MSG_process_suspend
 .. doxygenfunction:: MSG_process_unref
+.. doxygenfunction:: MSG_process_userdata_init
 .. doxygenfunction:: MSG_process_yield
 
-Host Management Functions
--------------------------
+Host Management
+===============
 
 .. doxygentypedef:: msg_host_t
 .. doxygenfunction:: MSG_host_by_name
@@ -118,13 +104,13 @@ Host Management Functions
 .. doxygenfunction:: MSG_host_get_mounted_storage_list
 .. doxygenfunction:: MSG_host_get_name
 .. doxygenfunction:: MSG_host_get_nb_pstates
+.. doxygenfunction:: MSG_host_get_load
 .. doxygenfunction:: MSG_host_get_power_peak_at
 .. doxygenfunction:: MSG_host_get_process_list
 .. doxygenfunction:: MSG_host_get_properties
 .. doxygenfunction:: MSG_host_get_property_value
 .. doxygenfunction:: MSG_host_get_pstate
 .. doxygenfunction:: MSG_host_get_speed
-.. doxygenfunction:: MSG_host_is_off
 .. doxygenfunction:: MSG_host_is_on
 .. doxygenfunction:: MSG_host_off
 .. doxygenfunction:: MSG_host_on
@@ -134,8 +120,8 @@ Host Management Functions
 .. doxygenfunction:: MSG_host_set_property_value
 .. doxygenfunction:: MSG_host_set_pstate
 
-Task Management Functions
--------------------------
+Task Management
+===============
 
 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
 
@@ -168,12 +154,10 @@ Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
 .. doxygenfunction:: MSG_task_listen_from
 .. doxygenfunction:: MSG_task_receive
 .. doxygenfunction:: MSG_task_receive_bounded
-.. doxygenfunction:: MSG_task_receive_ext
-.. doxygenfunction:: MSG_task_receive_ext_bounded
 .. doxygenfunction:: MSG_task_receive_with_timeout
 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
-.. doxygenfunction:: MSG_task_recv
-.. doxygenfunction:: MSG_task_recv_bounded
+.. doxygendefine:: MSG_task_recv
+.. doxygendefine:: MSG_task_recv_bounded
 .. doxygenfunction:: MSG_task_send
 .. doxygenfunction:: MSG_task_send_bounded
 .. doxygenfunction:: MSG_task_send_with_timeout
@@ -181,20 +165,19 @@ Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
 .. doxygenfunction:: MSG_task_set_bound
 .. doxygenfunction:: MSG_task_set_bytes_amount
 .. doxygenfunction:: MSG_task_set_category
-.. doxygenfunction:: MSG_task_set_copy_callback
 .. doxygenfunction:: MSG_task_set_data
 .. doxygenfunction:: MSG_task_set_flops_amount
 .. doxygenfunction:: MSG_task_set_name
 .. doxygenfunction:: MSG_task_set_priority
 
 		   
-Mailbox Management Functions
-----------------------------
+Mailbox Management
+==================
 
 .. doxygenfunction:: MSG_mailbox_set_async
 
 Communications
---------------
+==============
 
 .. doxygentypedef:: msg_comm_t
 
@@ -207,15 +190,15 @@ Communications
 .. doxygenfunction:: MSG_comm_waitall
 .. doxygenfunction:: MSG_comm_waitany
 
-Explicit Synchronization Functions
-----------------------------------
+Explicit Synchronization
+========================
 
 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
 
 In some situations, these things are very helpful to synchronize processes without message exchanges.
 
 Barriers
-........
+--------
 
 .. doxygentypedef:: msg_bar_t
 .. doxygenfunction:: MSG_barrier_destroy
@@ -223,7 +206,7 @@ Barriers
 .. doxygenfunction:: MSG_barrier_wait
 
 Semaphores
-..........
+----------
 		     
 .. doxygentypedef:: msg_sem_t
 .. doxygenfunction:: MSG_sem_acquire
@@ -235,7 +218,7 @@ Semaphores
 .. doxygenfunction:: MSG_sem_would_block
 
 Virtual Machines
-----------------
+================
 
 This interface mimics IaaS clouds.
 With it, you can create virtual machines to put your processes
@@ -243,7 +226,6 @@ into, and interact directly with the VMs to manage groups of
 processes.
 
 .. doxygentypedef:: msg_vm_t
-.. doxygenfunction:: MSG_vm_create
 .. doxygenfunction:: MSG_vm_create_core
 .. doxygenfunction:: MSG_vm_create_multicore
 .. doxygenfunction:: MSG_vm_destroy
@@ -260,8 +242,8 @@ processes.
 .. doxygenfunction:: MSG_vm_start
 .. doxygenfunction:: MSG_vm_suspend
 
-Storage Management Functions
-----------------------------
+Storage Management
+==================
 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
 
 .. doxygentypedef:: msg_storage_t
@@ -277,8 +259,8 @@ Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, i
 .. doxygenfunction:: MSG_storage_set_property_value
 .. doxygenfunction:: MSG_storage_write
 
-Zone Management Functions
--------------------------
+NetZone Management
+==================
 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
 
 .. doxygentypedef:: msg_netzone_t
@@ -289,3 +271,128 @@ Network Zone (:cpp:class:`msg_file_t`) and associated functions.
 .. doxygenfunction:: MSG_zone_get_root
 .. doxygenfunction:: MSG_zone_get_sons
 .. doxygenfunction:: MSG_zone_set_property_value
+
+Java bindings
+*************
+
+This section describes jMSG, the Java API to Simgrid. This API mimicks 
+:ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
+The full reference documentation is provided at the end of this page.
+
+Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
+directly to the Java bindings (any divergence is seen as a bug that we
+should fix). MSG structures are mapped to Java objects as expected,
+and the MSG functions are methods in these objects.
+
+Installing the Java bindings
+============================
+
+The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
+but some people may prefer to :ref:`compile it from the sources <install_src>`.
+
+
+Using the Java bindings
+=======================
+
+In most cases, you can use the SimGrid bindings as if it was a Java
+library:
+
+.. code-block:: shell
+
+   $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
+   $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
+
+For example:
+
+.. code-block:: shell
+
+   $ cd examples/deprecated/java
+   $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml 
+
+Any SimGrid simulation (java or not) is usually constituted of several
+kind of actors or processes (classes extending @c Msg.Process) that
+are deployed over the hosts of the virtual platform. So, your code
+should declare these actors, plus a Main class in charge of deploying
+your actors on the platform. Please refer to the examples for details.
+
+Troubleshooting
+===============
+
+Actually, these bindings are not only implemented in Java. They do use
+the C implementation of SimGrid. This should be transparent as this
+library is directly included in the ``simgrid.jar`` file but things can
+still go wrong is several ways.
+
+Error: library simgrid not found
+--------------------------------
+
+This means that the JVM fails to load the native library. If you use a
+precompiled jarfile, please report this bug.
+
+If you built it yourself, you can try to use an installed version of
+the library instead of the one included in the jar. For that, add the
+path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
+the ``DYLD_LIBRARY_PATH`` on macOS).
+
+pthread_create failed
+---------------------
+
+You reached the amount of threads that can be run on your system. Try
+increasing the thread limits of your operating system.
+
+Other errors
+------------
+
+When using jMSG, your program can crash for 3 main reasons:
+
+- Your Java part is not good: you'll have a good old java exception thrown,
+  and hence you should be able to correct it by yourself.
+- Our java part is not good: you'll also have a java exception thrown, but
+  we have real doubts this can happen, since the java part is only a JNI
+  binding. The other option is that it crashed because you used incorrectly
+  the MSG API, so this means also you should have an MSGException. It means
+  you should read carefully MSG samples and/or documentation.
+- Something has crashed in the C part. Okay, here comes the tricky
+  thing. It happens mainly for 2 reasons:
+  
+  - When something goes wrong in your simulation, sometimes the C part stops
+    because you used SimGrid incorrectly, and JNI bindings are not fond of that.
+    It means that you'll have something that looks ugly, but you should be able
+    to identify what's going wrong in your code by carefully reading the whole
+    error message
+  - It may happen that the problem comes directly from SimGrid: in this case,
+    the error should be uglier. In that case, you may submit a bug directly to
+    SimGrid.
+
+API Reference
+=============
+
+Package org.simgrid.msg
+-----------------------
+
+.. java:package:: org.simgrid.msg
+
+.. toctree::
+   :maxdepth: 1
+
+   Class org.simgrid.msg.As <java/org/simgrid/msg/As>
+   Class org.simgrid.msg.Comm <java/org/simgrid/msg/Comm>
+   Class org.simgrid.msg.File <java/org/simgrid/msg/File>
+   Class org.simgrid.msg.Host <java/org/simgrid/msg/Host>
+   Class org.simgrid.msg.HostFailureException <java/org/simgrid/msg/HostFailureException>
+   Class org.simgrid.msg.HostNotFoundException <java/org/simgrid/msg/HostNotFoundException>
+   Class org.simgrid.msg.JniException <java/org/simgrid/msg/JniException>
+   Class org.simgrid.msg.Msg <java/org/simgrid/msg/Msg>
+   Class org.simgrid.msg.MsgException <java/org/simgrid/msg/MsgException>
+   Class org.simgrid.msg.Mutex <java/org/simgrid/msg/Mutex>
+   Class org.simgrid.msg.Process <java/org/simgrid/msg/Process>
+   Class org.simgrid.msg.ProcessKilledError <java/org/simgrid/msg/ProcessKilledError>
+   Class org.simgrid.msg.ProcessNotFoundException <java/org/simgrid/msg/ProcessNotFoundException>
+   Class org.simgrid.msg.Semaphore <java/org/simgrid/msg/Semaphore>
+   Class org.simgrid.msg.Storage <java/org/simgrid/msg/Storage>
+   Class org.simgrid.msg.StorageNotFoundException <java/org/simgrid/msg/StorageNotFoundException>
+   Class org.simgrid.msg.Task <java/org/simgrid/msg/Task>
+   Class org.simgrid.msg.TaskCancelledException <java/org/simgrid/msg/TaskCancelledException>
+   Class org.simgrid.msg.TimeoutException <java/org/simgrid/msg/TimeoutException>
+   Class org.simgrid.msg.TransferFailureException <java/org/simgrid/msg/TransferFailureException>
+   Class org.simgrid.msg.VM <java/org/simgrid/msg/VM>