1 /** \addtogroup MSG_API
3 MSG was the first distributed programming environment provided within SimGrid,
4 and is still the most commonly used nowadays. If you are unsure of the interface
5 you should use, they you probably want to use MSG. It constitutes a convenient
6 simplification of the reality of distributed systems. It can be used to build
7 rather realistic simulations, but remains simple to use: most unpleasant
8 technical elements can be abstracted away rather easily. If you want to use the
9 C programming language, your are in the right section. If you prefer not to use
10 this venerable but demanding language, please refer to the @ref MSG_Java section.
12 If you think that MSG may not be the interface you need, please consider the
13 other user interfaces provided by SimGrid: If you want to use DAGs, have a look
14 at the \ref SD_API programming environment. If you want to study an existing MPI
15 program, have a look at the \ref SMPI_API one. If none of those programming
16 environments fits your needs, you may consider implementing your own directly on
17 top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
18 us before digging into these badly documented internal modules).
22 \section MSG_funct Offered functionalities
24 - \ref m_process_management
25 - \ref m_host_management
26 - \ref m_task_management
27 - \ref msg_mailbox_management
28 - \ref msg_file_management
32 - \ref msg_trace_driven
36 Also make sure to visit the page @ref MSG_examples.
42 @defgroup msg_simulation Main MSG simulation Functions
44 @brief Describes how to setup and control your simulation.
46 The basic workflow is the following (check the \ref MSG_examples for
49 -# Initialize the library with #MSG_init
50 -# Create a platform (usually by parsing a file with
51 #MSG_create_environment)
52 -# Register the functions that your processes are supposed to run with
53 #MSG_function_register (and maybe #MSG_function_register_default)
54 -# Launch your processes from a deployment file with #MSG_launch_application
55 -# Run the simulation with #MSG_main
57 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
60 /** @defgroup m_process_management Process Management Functions
62 * @brief This section describes the process structure of MSG
63 * (#msg_process_t) and the functions for managing it.
66 /** @defgroup m_host_management Host Management Functions
68 * @brief This section describes the host structure of MSG
71 /** @defgroup m_task_management Task Management Functions
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.
77 * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
80 /** @defgroup msg_mailbox_management Mailbox Management Functions
82 * @brief This section describes the mailbox structure of MSG
83 * (#msg_mailbox_t) and the functions for managing it.
85 * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Mailbox" --> \endhtmlonly
88 /** @defgroup msg_task_usage Task Actions
90 * @brief This section describes the functions that can be used
91 * by a process to execute, communicate or otherwise handle some task.
94 /** @defgroup msg_synchro Explicit Synchronization Functions
96 * @brief This section describes several explicit synchronization
97 * mechanisms existing in MSG: semaphores (#msg_sem_t) and friends.
99 * In some situations, these things are very helpful to synchronize processes without message exchanges.
102 /** @defgroup msg_VMs VMs
104 * @brief This section describes the interface created to mimic IaaS clouds.
106 * With it, you can create virtual machines to put your processes
107 * into, and interact directly with the VMs to manage groups of
110 * This interface is highly experimental at this point. Testing is
111 * welcomed, but do not expect too much of it right now. Even the
112 * interfaces may be changed in future releases of SimGrid (although
113 * things are expected to stabilize nicely before SimGrid v3.8).
114 * There is no guaranty on the rest of SimGrid, and there is less
115 * than that on this part.
119 /** @defgroup msg_storage_management Storage Management Functions
121 * @brief This section describes the storage structure of MSG
122 * (#msg_storage_t) and the functions for managing it. It
123 * is based on POSIX functions.
126 /** @defgroup msg_file_management File Management Functions
128 * @brief This section describes the file structure of MSG
129 * (#msg_file_t) and the functions for managing it. It
130 * is based on POSIX functions.
134 @defgroup msg_trace_driven Trace-driven simulations
136 @brief This section describes the functions allowing to build trace-driven simulations.
138 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
140 This is very handy when you want to test an algorithm or protocol that
141 does nothing unless it receives some events from outside. For example,
142 a P2P protocol reacts to requests from the user, but does nothing if
143 there is no such event.
145 In such situations, SimGrid allows to write your protocol in your C
146 file, and the events to react to in a separate text file. Declare a
147 function handling each of the events that you want to accept in your
148 trace files, register them using #xbt_replay_action_register in your main,
149 and then use #MSG_action_trace_run to launch the simulation. You can
150 either have one trace file containing all your events, or a file per
153 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
159 @defgroup MSG_examples MSG examples
164 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.
167 - @ref msg_ex_process
168 - @ref msg_ex_tracing
169 - @ref msg_ex_tracing_user_variables
172 - @ref msg_ex_actions
173 - @ref msg_ex_full_apps
176 \section msg_ex_basic Basic examples