-/** \addtogroup MSG_API
-
-MSG was the first distributed programming environment provided within SimGrid,
-and is still the most commonly used nowadays. If you are unsure of the interface
-you should use, they you probably want to use MSG. 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. If you want to use the
-C programming language, your are in the right section. If you prefer not to use
-this venerable but demanding language, please refer to the @ref MSG_Java section.
-
-If you think that MSG may not be the interface you need, please consider the
-other user interfaces provided by SimGrid: If you want to use DAGs, have a look
-at the \ref SD_API programming environment. If you want to study an existing MPI
-program, have a look at the \ref SMPI_API one. If none of those programming
-environments fits your needs, you may consider implementing your own directly on
-top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
-us before digging into these badly documented internal modules).
-
-
-
-\section MSG_funct Offered functionalities
- - \ref msg_simulation
- - \ref m_process_management
- - \ref m_host_management
- - \ref m_task_management
- - \ref msg_mailbox_management
- - \ref msg_file_management
- - \ref msg_task_usage
- - \ref msg_VMs
- - \ref msg_synchro
- - \ref msg_trace_driven
- - \ref MSG_examples
-
-
- Also make sure to visit the page @ref MSG_examples.
-*/
-
-
+/**
+@defgroup MSG_API MSG: Legacy handling of CSP algorithms
+@brief Simple programming environment
+
+
+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.
+
+@warning MSG used to be the main API of SimGrid 3, but we are
+ currently in the process of releasing SimGrid 4. The
+ tentative release date is Summer 2018. 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.
+
+@section MSG_funct Offered functionalities
+ - @ref msg_simulation
+ - @ref m_process_management
+ - @ref m_host_management
+ - @ref m_task_management
+ - @ref msg_mailbox_management
+ - @ref msg_file
+ - @ref msg_task_usage
+ - @ref msg_VMs
+ - @ref msg_synchro
+ - @ref msg_examples
+
+*/
/**
@defgroup msg_simulation Main MSG simulation Functions
@ingroup MSG_API
-@brief Describes how to setup and control your simulation.
+@brief How to setup and control your simulation.
-The basic workflow is the following (check the \ref MSG_examples for
+The basic workflow is the following (check the @ref msg_examples for
details).
-# Initialize the library with #MSG_init
/** @defgroup m_host_management Host Management Functions
* @ingroup MSG_API
- * @brief This section describes the host structure of MSG
+ * @brief Host structure of MSG
*/
/** @defgroup m_task_management Task Management Functions
* @ingroup MSG_API
- * @brief This section describes the task structure of MSG
- * (#msg_task_t) and the functions for managing it. See
- * \ref msg_task_usage to see how to put the tasks in action.
+ * @brief Task structure of MSG (#msg_task_t) and associated functions. See
+ * @ref msg_task_usage to see how to put the tasks in action.
*/
/** @defgroup msg_mailbox_management Mailbox Management Functions
* @ingroup MSG_API
- * @brief This section describes the mailbox structure of MSG
- * (#msg_mailbox_t) and the functions for managing it.
+ * @brief Functions associated to mailboxes.
*/
/** @defgroup msg_task_usage Task Actions
/** @defgroup msg_synchro Explicit Synchronization Functions
* @ingroup MSG_API
- * @brief This section describes several explicit synchronization
- * mechanisms existing in MSG: semaphores (#msg_sem_t) and friends.
+ * @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
*
* In some situations, these things are very helpful to synchronize processes without message exchanges.
*/
/** @defgroup msg_VMs VMs
* @ingroup MSG_API
- * @brief This section describes the interface created to mimic IaaS clouds.
+ * @brief Interface created to mimic 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.
*
- * This interface is highly experimental at this point. Testing is
- * welcomed, but do not expect too much of it right now. Even the
- * interfaces may be changed in future releases of SimGrid (although
- * things are expected to stabilize nicely before SimGrid v3.8).
- * There is no guaranty on the rest of SimGrid, and there is less
- * than that on this part.
- *
*/
/** @defgroup msg_storage_management Storage Management Functions
* @ingroup MSG_API
- * @brief This section describes the storage structure of MSG
- * (#msg_storage_t) and the functions for managing it. It
- * is based on POSIX functions.
- */
-
-/** @defgroup msg_file_management File Management Functions
- * @ingroup MSG_API
- * @brief This section describes the file structure of MSG
- * (#msg_file_t) and the functions for managing it. It
- * is based on POSIX functions.
+ * @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
*/
-/**
-@defgroup msg_trace_driven Trace-driven simulations
-@ingroup MSG_API
-@brief This section describes the functions allowing to build trace-driven simulations.
-
-This is very handy when you want to test an algorithm or protocol that
-does nothing unless it receives some events from outside. For example,
-a P2P protocol reacts to requests from the user, but does nothing if
-there is no such event.
-
-In such situations, SimGrid allows to write your protocol in your C
-file, and the events to react to in a separate text file. Declare a
-function handling each of the events that you want to accept in your
-trace files, register them using #xbt_replay_action_register in your main,
-and then use #MSG_action_trace_run to launch the simulation. You can
-either have one trace file containing all your events, or a file per
-simulated process.
-
-Check the examples in <b>examples/msg/actions/actions.c</b> for details.
-
- */
+/** @defgroup msg_file File Management Functions
+ @ingroup MSG_API
+ @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
+*/
