X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e709643ef0c5b61c6c878016c418bffa2b1b20cd..HEAD:/docs/source/app_msg.rst diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst deleted file mode 100644 index f68fe2d38e..0000000000 --- a/docs/source/app_msg.rst +++ /dev/null @@ -1,399 +0,0 @@ -.. _MSG_doc: - -The MSG Interface (legacy interface) -#################################### - -.. 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 -constitutes a convenient simplification of the reality of distributed -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. - -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`) - - Launch your processes from a deployment file with :cpp:func:`MSG_launch_application` - - Run the simulation with :cpp:func:`MSG_main` - -.. doxygenenum:: msg_error_t - -.. doxygenfunction:: MSG_config -.. doxygenfunction:: MSG_create_environment -.. doxygenfunction:: MSG_function_register -.. doxygenfunction:: MSG_function_register_default -.. doxygenfunction:: MSG_get_clock -.. doxygenfunction:: MSG_get_sent_msg -.. doxygendefine:: MSG_init -.. doxygenfunction:: MSG_launch_application -.. doxygenfunction:: MSG_main - -Process Management -================== - -This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it. - -.. doxygentypedef:: msg_process_t -.. doxygenfunction:: MSG_process_attach -.. doxygenfunction:: MSG_process_auto_restart_set -.. doxygenfunction:: MSG_process_create -.. doxygenfunction:: MSG_process_create_with_arguments -.. doxygenfunction:: MSG_process_create_with_environment -.. 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_is_suspended -.. doxygenfunction:: MSG_process_join -.. doxygenfunction:: MSG_process_kill -.. doxygenfunction:: MSG_process_killall -.. doxygenfunction:: MSG_process_migrate -.. doxygenfunction:: MSG_process_on_exit -.. doxygenfunction:: MSG_process_ref -.. doxygenfunction:: MSG_process_restart -.. doxygenfunction:: MSG_process_resume -.. doxygenfunction:: MSG_process_self -.. doxygenfunction:: MSG_process_self_name -.. doxygenfunction:: MSG_process_self_PID -.. doxygenfunction:: MSG_process_self_PPID -.. doxygenfunction:: MSG_process_set_data -.. doxygenfunction:: MSG_process_set_data_cleanup -.. doxygenfunction:: MSG_process_set_kill_time -.. doxygenfunction:: MSG_process_sleep -.. doxygenfunction:: MSG_process_suspend -.. doxygenfunction:: MSG_process_unref -.. doxygenfunction:: MSG_process_yield - -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_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 -=============== - -Task structure of MSG :cpp:type:`msg_task_t` and associated functions. - -.. doxygentypedef:: msg_task_t -.. doxygendefine:: MSG_TASK_UNINITIALIZED - -.. doxygenfunction:: MSG_parallel_task_create -.. doxygenfunction:: MSG_parallel_task_execute -.. doxygenfunction:: MSG_parallel_task_execute_with_timeout -.. doxygenfunction:: MSG_task_cancel -.. doxygenfunction:: MSG_task_create -.. doxygenfunction:: MSG_task_destroy -.. doxygenfunction:: MSG_task_dsend -.. doxygenfunction:: MSG_task_dsend_bounded -.. doxygenfunction:: MSG_task_execute -.. doxygenfunction:: MSG_task_get_bytes_amount -.. doxygenfunction:: MSG_task_get_category -.. doxygenfunction:: MSG_task_get_data -.. doxygenfunction:: MSG_task_get_flops_amount -.. doxygenfunction:: MSG_task_get_name -.. doxygenfunction:: MSG_task_get_remaining_communication -.. doxygenfunction:: MSG_task_get_remaining_work_ratio -.. doxygenfunction:: MSG_task_get_sender -.. doxygenfunction:: MSG_task_get_source -.. doxygenfunction:: MSG_task_irecv -.. doxygenfunction:: MSG_task_irecv_bounded -.. doxygenfunction:: MSG_task_isend -.. doxygenfunction:: MSG_task_isend_bounded -.. doxygenfunction:: MSG_task_listen -.. doxygenfunction:: MSG_task_listen_from -.. doxygenfunction:: MSG_task_receive -.. doxygenfunction:: MSG_task_receive_bounded -.. doxygenfunction:: MSG_task_receive_with_timeout -.. doxygenfunction:: MSG_task_receive_with_timeout_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 -.. doxygenfunction:: MSG_task_send_with_timeout_bounded -.. doxygenfunction:: MSG_task_set_bound -.. doxygenfunction:: MSG_task_set_bytes_amount -.. doxygenfunction:: MSG_task_set_category -.. doxygenfunction:: MSG_task_set_data -.. doxygenfunction:: MSG_task_set_flops_amount -.. doxygenfunction:: MSG_task_set_name -.. doxygenfunction:: MSG_task_set_priority - - -Mailbox Management -================== - -.. doxygenfunction:: MSG_mailbox_set_async - -Communications -============== - -.. doxygentypedef:: msg_comm_t - -.. doxygenfunction:: MSG_comm_destroy -.. doxygenfunction:: MSG_comm_get_status -.. doxygenfunction:: MSG_comm_get_task -.. doxygenfunction:: MSG_comm_test -.. doxygenfunction:: MSG_comm_testany -.. doxygenfunction:: MSG_comm_wait -.. doxygenfunction:: MSG_comm_waitall -.. doxygenfunction:: MSG_comm_waitany - -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 -.. doxygenfunction:: MSG_barrier_init -.. doxygenfunction:: MSG_barrier_wait - -Semaphores ----------- - -.. doxygentypedef:: msg_sem_t -.. doxygenfunction:: MSG_sem_acquire -.. doxygenfunction:: MSG_sem_acquire_timeout -.. doxygenfunction:: MSG_sem_destroy -.. doxygenfunction:: MSG_sem_get_capacity -.. doxygenfunction:: MSG_sem_init -.. doxygenfunction:: MSG_sem_release -.. doxygenfunction:: MSG_sem_would_block - -Virtual Machines -================ - -This interface mimics IaaS clouds. -With it, you can create virtual machines to put your processes -into, and interact directly with the VMs to manage groups of -processes. - -.. doxygentypedef:: msg_vm_t -.. doxygenfunction:: MSG_vm_create_core -.. doxygenfunction:: MSG_vm_create_multicore -.. doxygenfunction:: MSG_vm_destroy -.. doxygenfunction:: MSG_vm_get_name -.. doxygenfunction:: MSG_vm_get_pm -.. doxygenfunction:: MSG_vm_get_ramsize -.. doxygenfunction:: MSG_vm_is_created -.. doxygenfunction:: MSG_vm_is_running -.. doxygenfunction:: MSG_vm_is_suspended -.. doxygenfunction:: MSG_vm_resume -.. doxygenfunction:: MSG_vm_set_bound -.. doxygenfunction:: MSG_vm_set_ramsize -.. doxygenfunction:: MSG_vm_shutdown -.. doxygenfunction:: MSG_vm_start -.. doxygenfunction:: MSG_vm_suspend - -Storage Management -================== -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 - -NetZone Management -================== -Network Zone (:cpp:class:`msg_file_t`) and associated functions. - -.. doxygentypedef:: msg_netzone_t -.. doxygenfunction:: MSG_zone_get_by_name -.. doxygenfunction:: MSG_zone_get_hosts -.. doxygenfunction:: MSG_zone_get_name -.. doxygenfunction:: MSG_zone_get_property_value -.. 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 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:: 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.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