doc/doxygen/module-msg.doc

   1 /**
   2 @defgroup MSG_API  MSG: Simple API for Concurrent Sequential Process Algorithms
   3 @brief Simple programming environment
   4
   5 MSG was the first distributed programming environment provided within SimGrid,
   6 and is still the most commonly used nowadays. If you are unsure of the interface
   7 you should use, they you probably want to use MSG. It constitutes a convenient
   8 simplification of the reality of distributed systems. It can be used to build
   9 rather realistic simulations, but remains simple to use: most unpleasant
  10 technical elements can be abstracted away rather easily.  If you want to use the
  11 C programming language, your are in the right section. If you prefer not to use
  12 this venerable but demanding language, please refer to the @ref MSG_Java section.
  13
  14 If you think that MSG may not be the interface you need, please consider the
  15 other user interfaces provided by SimGrid: If you want to use DAGs, have a look
  16 at the \ref SD_API programming environment. If you want to study an existing MPI
  17 program, have a look at the \ref SMPI_API one. If none of those programming
  18 environments fits your needs, you may consider implementing your own directly on
  19 top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
  20 us before digging into these badly documented internal modules).
  21
  22
  23
  24 \section MSG_funct Offered functionalities
  25    - \ref msg_simulation
  26    - \ref m_process_management
  27    - \ref m_host_management
  28    - \ref m_task_management
  29    - \ref msg_mailbox_management
  30    - \ref msg_file_management
  31    - \ref msg_task_usage
  32    - \ref msg_VMs
  33    - \ref msg_synchro
  34    - \ref msg_trace_driven
  35    - \ref MSG_examples
  36
  37
  38   Also make sure to visit the page @ref MSG_examples.
  39 */
  40
  41
  42
  43 /**
  44 @defgroup msg_simulation   Main MSG simulation Functions
  45 @ingroup MSG_API
  46 @brief Describes how to setup and control your simulation.
  47
  48 The basic workflow is the following (check the \ref MSG_examples for
  49 details).
  50
  51  -# Initialize the library with #MSG_init
  52  -# Create a platform (usually by parsing a file with
  53     #MSG_create_environment)
  54  -# Register the functions that your processes are supposed to run with
  55     #MSG_function_register (and maybe #MSG_function_register_default)
  56  -# Launch your processes from a deployment file with #MSG_launch_application
  57  -# Run the simulation with #MSG_main
  58 */
  59
  60 /** @defgroup m_process_management Process Management Functions
  61  *  @ingroup MSG_API
  62  *  @brief This section describes the process structure of MSG
  63  *         (#msg_process_t) and the functions for managing it.
  64  */
  65
  66 /** @defgroup m_host_management Host Management Functions
  67  *  @ingroup MSG_API
  68  *  @brief This section describes the host structure of MSG
  69  */
  70
  71 /** @defgroup m_task_management Task Management Functions
  72  *  @ingroup MSG_API
  73  *  @brief This section describes the task structure of MSG
  74  *         (#msg_task_t) and the functions for managing it. See
  75  *         \ref msg_task_usage to see how to put the tasks in action.
  76  */
  77
  78 /** @defgroup msg_mailbox_management Mailbox Management Functions
  79  *  @ingroup MSG_API
  80  *  @brief This section describes the mailbox structure of MSG
  81  *         (#msg_mailbox_t) and the functions for managing it.
  82  */
  83
  84 /** @defgroup msg_task_usage Task Actions
  85  *  @ingroup MSG_API
  86  *  @brief This section describes the functions that can be used
  87  *         by a process to execute, communicate or otherwise handle some task.
  88  */
  89
  90 /** @defgroup msg_synchro Explicit Synchronization Functions
  91  *  @ingroup MSG_API
  92  *  @brief This section describes several explicit synchronization
  93  *         mechanisms existing in MSG: semaphores (#msg_sem_t) and friends.
  94  *
  95  * In some situations, these things are very helpful to synchronize processes without message exchanges.
  96  */
  97
  98 /** @defgroup msg_VMs VMs
  99  *  @ingroup MSG_API
 100  *  @brief This section describes the interface created to mimic IaaS clouds.
 101  *
 102  *  With it, you can create virtual machines to put your processes
 103  *  into, and interact directly with the VMs to manage groups of
 104  *  processes.
 105  *
 106  *  This interface is highly experimental at this point. Testing is
 107  *  welcomed, but do not expect too much of it right now. Even the
 108  *  interfaces may be changed in future releases of SimGrid (although
 109  *  things are expected to stabilize nicely before SimGrid v3.8).
 110  *  There is no guaranty on the rest of SimGrid, and there is less
 111  *  than that on this part.
 112  *
 113  */
 114
 115 /** @defgroup msg_storage_management Storage Management Functions
 116  *  @ingroup MSG_API
 117  *  @brief This section describes the storage structure of MSG
 118  *         (#msg_storage_t) and the functions for managing it. It
 119  *   is based on POSIX functions.
 120  */
 121
 122 /** @defgroup msg_file_management File Management Functions
 123  *  @ingroup MSG_API
 124  *  @brief This section describes the file structure of MSG
 125  *         (#msg_file_t) and the functions for managing it. It
 126  *   is based on POSIX functions.
 127  */
 128
 129 /**
 130 @defgroup msg_trace_driven Trace-driven simulations
 131 @ingroup MSG_API
 132 @brief This section describes the functions allowing to build trace-driven simulations.
 133
 134 This is very handy when you want to test an algorithm or protocol that
 135 does nothing unless it receives some events from outside. For example,
 136 a P2P protocol reacts to requests from the user, but does nothing if
 137 there is no such event.
 138
 139 In such situations, SimGrid allows to write your protocol in your C
 140 file, and the events to react to in a separate text file. Declare a
 141 function handling each of the events that you want to accept in your
 142 trace files, register them using #xbt_replay_action_register in your main,
 143 and then use #MSG_action_trace_run to launch the simulation. You can
 144 either have one trace file containing all your events, or a file per
 145 simulated process.
 146
 147 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 148
 149  */