.. _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 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>