Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
0637b31a974a4312945319bc15967755a78c5855
[simgrid.git] / doc / doxygen / module-msg.doc
1 /**
2 @defgroup MSG_API  MSG: Simulate 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 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 Host structure of MSG
60  */
61
62 /** @defgroup m_task_management Task Management Functions
63  *  @ingroup MSG_API
64  *  @brief Task structure of MSG (#msg_task_t) and associated functions. See
65  *         \ref msg_task_usage to see how to put the tasks in action.
66  */
67
68 /** @defgroup msg_mailbox_management Mailbox Management Functions
69  *  @ingroup MSG_API
70  *  @brief Mailbox structure of MSG (#msg_mailbox_t) and associated functions.
71  */
72
73 /** @defgroup msg_task_usage Task Actions
74  *  @ingroup MSG_API
75  *  @brief This section describes the functions that can be used
76  *         by a process to execute, communicate or otherwise handle some task.
77  */
78
79 /** @defgroup msg_synchro Explicit Synchronization Functions
80  *  @ingroup MSG_API
81  *  @brief Explicit synchronization mechanisms: semaphores (#msg_sem_t) and friends.
82  *
83  * In some situations, these things are very helpful to synchronize processes without message exchanges.
84  */
85
86 /** @defgroup msg_VMs VMs
87  *  @ingroup MSG_API
88  *  @brief Interface created to mimic IaaS clouds.
89  *
90  *  With it, you can create virtual machines to put your processes
91  *  into, and interact directly with the VMs to manage groups of
92  *  processes.
93  *
94  *  This interface is highly experimental at this point. Testing is
95  *  welcomed, but do not expect too much of it right now. Even the
96  *  interfaces may be changed in future releases of SimGrid (although
97  *  things are expected to stabilize nicely before SimGrid v3.8).
98  *  There is no guaranty on the rest of SimGrid, and there is less
99  *  than that on this part.
100  *
101  */
102
103 /** @defgroup msg_storage_management Storage Management Functions
104  *  @ingroup MSG_API
105  *  @brief Storage structure of MSG (#msg_storage_t) and associated functions, inspired from POSIX.
106  */
107
108 /** @defgroup msg_file File Management Functions
109     @ingroup MSG_API
110     @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX.
111 */
112
113 /**
114 @defgroup msg_trace_driven Trace-driven simulations
115 @ingroup MSG_API
116 @brief This section describes the functions allowing to build trace-driven simulations.
117
118 This is very handy when you want to test an algorithm or protocol that
119 does nothing unless it receives some events from outside. For example,
120 a P2P protocol reacts to requests from the user, but does nothing if
121 there is no such event.
122
123 In such situations, SimGrid allows to write your protocol in your C
124 file, and the events to react to in a separate text file. Declare a
125 function handling each of the events that you want to accept in your
126 trace files, register them using #xbt_replay_action_register in your main,
127 and then use #MSG_action_trace_run to launch the simulation. You can
128 either have one trace file containing all your events, or a file per
129 simulated process.
130
131 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
132
133  */