Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
3ef2a6c0690c2f21aa1279b4cf3e53b6d38d8af7
[simgrid.git] / 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  */