From d1049a71a96c2026dbe8cb9670af5a536246420a Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 29 Jun 2019 00:55:07 +0200 Subject: [PATCH] doc: Move Java as a subtree of MSG --- ChangeLog | 7 ++ docs/source/app_java.rst | 140 ------------------------ docs/source/app_msg.rst | 181 +++++++++++++++++++++++++------ docs/source/index.rst | 1 - tools/cmake/DefinePackages.cmake | 1 - 5 files changed, 154 insertions(+), 176 deletions(-) delete mode 100644 docs/source/app_java.rst diff --git a/ChangeLog b/ChangeLog index d8c7bf79e8..a0eaf8dca7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -2,6 +2,13 @@ SimGrid (3.23.1) NOT RELEASED YET (v3.24 expected September 23. 7:50 UTC) +Documentation: + - Nicer introduction page. + - Move Java as a subtree of MSG. + +Bugs: + - Really fix FG#26: Turning off a link should raise NetworkFailureException + ---------------------------------------------------------------------------- SimGrid (3.23) June 25. 2019 diff --git a/docs/source/app_java.rst b/docs/source/app_java.rst deleted file mode 100644 index e77587c5f9..0000000000 --- a/docs/source/app_java.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _Java_doc: - -The Java Bindings -################# - -.. raw:: html - - - -
-
- - -This section describes jMSG, the Java API to Simgrid. This API mimicks -:ref:`MSG `, 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 ` 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 `, -but some people may prefer to :ref:`compile it from the sources `. - - -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 - Class org.simgrid.msg.Comm - Class org.simgrid.msg.File - Class org.simgrid.msg.Host - Class org.simgrid.msg.HostFailureException - Class org.simgrid.msg.HostNotFoundException - Class org.simgrid.msg.JniException - Class org.simgrid.msg.Msg - Class org.simgrid.msg.MsgException - Class org.simgrid.msg.Mutex - Class org.simgrid.msg.Process - Class org.simgrid.msg.ProcessKilledError - Class org.simgrid.msg.ProcessNotFoundException - Class org.simgrid.msg.RngStream - Class org.simgrid.msg.Semaphore - Class org.simgrid.msg.Storage - Class org.simgrid.msg.StorageNotFoundException - Class org.simgrid.msg.Task - Class org.simgrid.msg.TaskCancelledException - Class org.simgrid.msg.TimeoutException - Class org.simgrid.msg.TransferFailureException - Class org.simgrid.msg.VM diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst index a7853f73a7..511b907778 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:: - - -
-
+ 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 ` 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: @@ -60,7 +47,7 @@ The basic workflow is the following: .. doxygenfunction:: MSG_set_function Process Management Functions ----------------------------- +============================ This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it. @@ -104,7 +91,7 @@ This describes the process structure :cpp:type:`msg_process_t` and the functions .. doxygenfunction:: MSG_process_yield Host Management Functions -------------------------- +========================= .. doxygentypedef:: msg_host_t .. doxygenfunction:: MSG_host_by_name @@ -133,7 +120,7 @@ Host Management Functions .. doxygenfunction:: MSG_host_set_pstate Task Management Functions -------------------------- +========================= Task structure of MSG :cpp:type:`msg_task_t` and associated functions. @@ -187,12 +174,12 @@ Task structure of MSG :cpp:type:`msg_task_t` and associated functions. Mailbox Management Functions ----------------------------- +============================ .. doxygenfunction:: MSG_mailbox_set_async Communications --------------- +============== .. doxygentypedef:: msg_comm_t @@ -206,14 +193,14 @@ Communications .. doxygenfunction:: MSG_comm_waitany Explicit Synchronization Functions ----------------------------------- +================================== 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 @@ -221,7 +208,7 @@ Barriers .. doxygenfunction:: MSG_barrier_wait Semaphores -.......... +---------- .. doxygentypedef:: msg_sem_t .. doxygenfunction:: MSG_sem_acquire @@ -233,7 +220,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 @@ -258,7 +245,7 @@ processes. .. doxygenfunction:: MSG_vm_suspend Storage Management Functions ----------------------------- +============================ Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX. .. doxygentypedef:: msg_storage_t @@ -275,7 +262,7 @@ Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, i .. doxygenfunction:: MSG_storage_write Zone Management Functions -------------------------- +========================= Network Zone (:cpp:class:`msg_file_t`) and associated functions. .. doxygentypedef:: msg_netzone_t @@ -286,3 +273,129 @@ 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 `, 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 ` 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 `, +but some people may prefer to :ref:`compile it from the sources `. + + +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 + Class org.simgrid.msg.Comm + Class org.simgrid.msg.File + Class org.simgrid.msg.Host + Class org.simgrid.msg.HostFailureException + Class org.simgrid.msg.HostNotFoundException + Class org.simgrid.msg.JniException + Class org.simgrid.msg.Msg + Class org.simgrid.msg.MsgException + Class org.simgrid.msg.Mutex + Class org.simgrid.msg.Process + Class org.simgrid.msg.ProcessKilledError + Class org.simgrid.msg.ProcessNotFoundException + Class org.simgrid.msg.RngStream + Class org.simgrid.msg.Semaphore + Class org.simgrid.msg.Storage + Class org.simgrid.msg.StorageNotFoundException + Class org.simgrid.msg.Task + Class org.simgrid.msg.TaskCancelledException + Class org.simgrid.msg.TimeoutException + Class org.simgrid.msg.TransferFailureException + Class org.simgrid.msg.VM diff --git a/docs/source/index.rst b/docs/source/index.rst index 79e46c8b32..e5a01946a3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -73,7 +73,6 @@ of every page. Bugs in the code should be reported    The S4U Interface    The SMPI Interface    The MSG Interface -    The Java Bindings Describing the Simulated Platform    Modeling Hints    DTD Reference diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 81dd93e68a..ad836e8e46 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -881,7 +881,6 @@ set(DOC_SOURCES docs/ignored_symbols docs/source/application.rst - docs/source/app_java.rst docs/source/app_msg.rst docs/source/app_s4u.rst docs/source/app_smpi.rst -- 2.20.1