X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a300feccc8b5c35a9c5abdc44864c434760730b2..2a999ac2440bf73a4b7882a728e01d3485e0982a:/docs/source/app_msg.rst diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst index 04a3514578..ebfc632cca 100644 --- a/docs/source/app_msg.rst +++ b/docs/source/app_msg.rst @@ -1,20 +1,18 @@ .. _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 2020Q4 or 2021Q1. - - -
-
+ This interface is disabled by default. Pass -Denable_msg=ON to + cmake if you still need it. MSG is a simple API to write algorithms organized with Concurrent Sequential Processes (CSP) that interact by exchanging messages. It @@ -23,26 +21,18 @@ 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: - Initialize the library with :c:macro:`MSG_init` - Create a platform (usually by parsing a file with :cpp:func:`MSG_create_environment`) - Register the functions that your processes are supposed to run with - :cpp:func:`MSG_function_register` (and maybe :cpp:func:`MSG_function_register_default`) + :cpp:func:`MSG_function_register` (and maybe :cpp:func:`MSG_function_register_default`) - Launch your processes from a deployment file with :cpp:func:`MSG_launch_application` - Run the simulation with :cpp:func:`MSG_main` @@ -57,10 +47,9 @@ The basic workflow is the following: .. doxygendefine:: MSG_init .. doxygenfunction:: MSG_launch_application .. 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,20 +59,16 @@ 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 .. doxygenfunction:: MSG_process_from_PID .. doxygenfunction:: MSG_process_get_data .. doxygenfunction:: MSG_process_get_host .. doxygenfunction:: MSG_process_get_name -.. doxygenfunction:: MSG_process_get_number .. doxygenfunction:: MSG_process_get_PID .. 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 @@ -105,41 +90,39 @@ This describes the process structure :cpp:type:`msg_process_t` and the functions .. doxygenfunction:: MSG_process_unref .. doxygenfunction:: MSG_process_yield -Host Management Functions -------------------------- +Host Management +=============== .. doxygentypedef:: msg_host_t .. doxygenfunction:: MSG_host_by_name .. doxygenfunction:: MSG_get_host_by_name .. doxygenfunction:: MSG_get_host_number -.. doxygenfunction:: MSG_host_get_attached_storage_lists .. doxygenfunction:: MSG_host_get_core_number .. doxygenfunction:: MSG_host_get_data -.. 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 -.. doxygenfunction:: MSG_hosts_as_dynar .. doxygenfunction:: MSG_host_self .. doxygenfunction:: MSG_host_set_data .. 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. .. doxygentypedef:: msg_task_t +.. doxygentypedef:: const_msg_task_t .. doxygendefine:: MSG_TASK_UNINITIALIZED .. doxygenfunction:: MSG_parallel_task_create @@ -168,12 +151,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,23 +162,22 @@ 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 - +.. doxygentypedef:: const_msg_comm_t .. doxygenfunction:: MSG_comm_destroy .. doxygenfunction:: MSG_comm_get_status .. doxygenfunction:: MSG_comm_get_task @@ -207,15 +187,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,8 +203,8 @@ Barriers .. doxygenfunction:: MSG_barrier_wait Semaphores -.......... - +---------- + .. doxygentypedef:: msg_sem_t .. doxygenfunction:: MSG_sem_acquire .. doxygenfunction:: MSG_sem_acquire_timeout @@ -235,7 +215,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 +223,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,26 +239,9 @@ processes. .. doxygenfunction:: MSG_vm_start .. 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 -.. doxygenfunction:: MSG_storage_get_by_name -.. doxygenfunction:: MSG_storage_get_data -.. doxygenfunction:: MSG_storage_get_host -.. doxygenfunction:: MSG_storage_get_name -.. doxygenfunction:: MSG_storage_get_properties -.. doxygenfunction:: MSG_storage_get_property_value -.. doxygenfunction:: MSG_storage_read -.. doxygenfunction:: MSG_storages_as_dynar -.. doxygenfunction:: MSG_storage_set_data -.. doxygenfunction:: MSG_storage_set_property_value -.. doxygenfunction:: MSG_storage_write - -Zone Management Functions -------------------------- -Network Zone (:cpp:class:`msg_file_t`) and associated functions. +NetZone Management +================== +Network Zone (:cpp:type:`msg_netzone_t`) and associated functions. .. doxygentypedef:: msg_netzone_t .. doxygenfunction:: MSG_zone_get_by_name @@ -289,3 +251,130 @@ 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_doc: + +Java bindings +************* + +This section describes jMSG, the Java API to Simgrid. This API mimics +: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:: console + + $ 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:: console + + $ 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.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