X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/9d98c2be975bc2b812385686c987b4e6d569aa06..695a5d0b3490296b3df020da81d1e586f5d2f645:/doc/doxygen/module-msg.doc diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index 88bda8e631..5f3c420730 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -1,49 +1,43 @@ -/** \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 @@ -53,8 +47,6 @@ details). #MSG_function_register (and maybe #MSG_function_register_default) -# Launch your processes from a deployment file with #MSG_launch_application -# Run the simulation with #MSG_main - -@htmlonly @endhtmlonly */ /** @defgroup m_process_management Process Management Functions @@ -65,24 +57,18 @@ details). /** @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. - * - * \htmlonly \endhtmlonly + * @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. - * - * \htmlonly \endhtmlonly + * @brief Functions associated to mailboxes. */ /** @defgroup msg_task_usage Task Actions @@ -93,81 +79,27 @@ details). /** @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. - */ - -/** -@defgroup msg_trace_driven Trace-driven simulations -@ingroup MSG_API -@brief This section describes the functions allowing to build trace-driven simulations. - -\htmlonly \endhtmlonly - -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 examples/msg/actions/actions.c for details. - + * @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX. */ - -/** -@defgroup MSG_examples MSG examples -@ingroup MSG_API -@brief . - -Finding the right example in examples/msg is sometimes difficult. This list aims at helping you to find the example from which you can learn what you want to. - -\section msg_bsc_ex Basic examples - +/** @defgroup msg_file File Management Functions + @ingroup MSG_API + @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX. */ - - - - - -