doc/doxygen/module-msg.doc

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