doc/doxygen/module-msg.doc

   1 /**
   2 @defgroup MSG_API  MSG: Legacy handling of CSP algorithms
   3 @brief Simple programming environment
   4
   5
   6 MSG is a simple API to write algorithms organized with Concurrent
   7 Sequential Processes (CSP) that interact by exchanging messages. It
   8 constitutes a convenient simplification of the reality of distributed
   9 systems. It can be used to build rather realistic simulations, but
  10 remains simple to use: most unpleasant technical elements can be
  11 abstracted away rather easily.
  12
  13 \warning MSG used to be the main API of SimGrid 3, but we are
  14          currently in the process of releasing SimGrid 4. The
  15          tentative release date is Summer 2018. So MSG is frozen and
  16          will probably never evolve. If you are starting a new
  17          project, you should consider S4U instead. Note that the
  18          support for MSG will not be removed from SimGrid before 2020
  19          at least.
  20
  21 \section MSG_funct Offered functionalities
  22    - \ref msg_simulation
  23    - \ref m_process_management
  24    - \ref m_host_management
  25    - \ref m_task_management
  26    - \ref msg_mailbox_management
  27    - @ref msg_file
  28    - \ref msg_task_usage
  29    - \ref msg_VMs
  30    - \ref msg_synchro
  31    - \ref msg_trace_driven
  32    - \ref msg_examples
  33
  34 */
  35
  36 /**
  37 @defgroup msg_simulation   Main MSG simulation Functions
  38 @ingroup MSG_API
  39 @brief How to setup and control your simulation.
  40
  41 The basic workflow is the following (check the \ref msg_examples for
  42 details).
  43
  44  -# Initialize the library with #MSG_init
  45  -# Create a platform (usually by parsing a file with
  46     #MSG_create_environment)
  47  -# Register the functions that your processes are supposed to run with
  48     #MSG_function_register (and maybe #MSG_function_register_default)
  49  -# Launch your processes from a deployment file with #MSG_launch_application
  50  -# Run the simulation with #MSG_main
  51 */
  52
  53 /** @defgroup m_process_management Process Management Functions
  54  *  @ingroup MSG_API
  55  *  @brief This section describes the process structure of MSG
  56  *         (#msg_process_t) and the functions for managing it.
  57  */
  58
  59 /** @defgroup m_host_management Host Management Functions
  60  *  @ingroup MSG_API
  61  *  @brief Host structure of MSG
  62  */
  63
  64 /** @defgroup m_task_management Task Management Functions
  65  *  @ingroup MSG_API
  66  *  @brief Task structure of MSG (#msg_task_t) and associated functions. See
  67  *         \ref msg_task_usage to see how to put the tasks in action.
  68  */
  69
  70 /** @defgroup msg_mailbox_management Mailbox Management Functions
  71  *  @ingroup MSG_API
  72  *  @brief Functions associated to mailboxes.
  73  */
  74
  75 /** @defgroup msg_task_usage Task Actions
  76  *  @ingroup MSG_API
  77  *  @brief This section describes the functions that can be used
  78  *         by a process to execute, communicate or otherwise handle some task.
  79  */
  80
  81 /** @defgroup msg_synchro Explicit Synchronization Functions
  82  *  @ingroup MSG_API
  83  *  @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
  84  *
  85  * In some situations, these things are very helpful to synchronize processes without message exchanges.
  86  */
  87
  88 /** @defgroup msg_VMs VMs
  89  *  @ingroup MSG_API
  90  *  @brief Interface created to mimic IaaS clouds.
  91  *
  92  *  With it, you can create virtual machines to put your processes
  93  *  into, and interact directly with the VMs to manage groups of
  94  *  processes.
  95  *
  96  */
  97
  98 /** @defgroup msg_storage_management Storage Management Functions
  99  *  @ingroup MSG_API
 100  *  @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
 101  */
 102
 103 /** @defgroup msg_file File Management Functions
 104     @ingroup MSG_API
 105     @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
 106 */
 107
 108 /**
 109 @defgroup msg_trace_driven Trace-driven simulations
 110 @ingroup MSG_API
 111 @brief This section describes the functions allowing to build trace-driven simulations.
 112
 113 This is very handy when you want to test an algorithm or protocol that
 114 does nothing unless it receives some events from outside. For example,
 115 a P2P protocol reacts to requests from the user, but does nothing if
 116 there is no such event.
 117
 118 In such situations, SimGrid allows to write your protocol in your C
 119 file, and the events to react to in a separate text file. Declare a
 120 function handling each of the events that you want to accept in your
 121 trace files, register them using #xbt_replay_action_register in your main,
 122 and then use #MSG_action_trace_run to launch the simulation. You can
 123 either have one trace file containing all your events, or a file per
 124 simulated process.
 125
 126 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 127
 128  */