Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Various doc fixups
[simgrid.git] / docs / source / app_msg.rst
1 .. _MSG_doc:
2
3 ====================================
4 The MSG Interface (legacy interface)
5 ====================================
6
7 .. raw:: html
8
9    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
10    <script>
11    window.onload=function() { // Wait for the SVG to be loaded before changing it
12      //var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
13      //elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
14    }
15    </script>
16    <br/>
17    <br/>
18
19 MSG is a simple API to write algorithms organized with Concurrent
20 Sequential Processes (CSP) that interact by exchanging messages. It
21 constitutes a convenient simplification of the reality of distributed
22 systems. It can be used to build rather realistic simulations, but
23 remains simple to use: most unpleasant technical elements can be
24 abstracted away rather easily.
25
26 This page describes the C version of this API while the :ref:`Java
27 bindings of MSG <Java_doc>` are described in another section.
28
29 .. warning::
30
31    MSG used to be the main API of SimGrid 3, but we are currently in
32    the process of releasing SimGrid 4. So MSG is frozen and will
33    probably never evolve. If you are starting a new project, you
34    should consider S4U instead. Note that the support for MSG will not
35    be removed from SimGrid before 2020 at least.
36
37 Main MSG Functions
38 ------------------
39
40 The basic workflow is the following:
41
42  - Initialize the library with :c:macro:`MSG_init`
43  - Create a platform (usually by parsing a file with :cpp:func:`MSG_create_environment`)
44  - Register the functions that your processes are supposed to run with
45    :cpp:func:`MSG_function_register` (and maybe :cpp:func:`MSG_function_register_default`) 
46  - Launch your processes from a deployment file with :cpp:func:`MSG_launch_application`
47  - Run the simulation with :cpp:func:`MSG_main`
48
49 .. doxygenenum:: msg_error_t
50
51 .. doxygenfunction:: MSG_config
52 .. doxygenfunction:: MSG_create_environment
53 .. doxygenfunction:: MSG_function_register
54 .. doxygenfunction:: MSG_function_register_default
55 .. doxygenfunction:: MSG_get_clock
56 .. doxygenfunction:: MSG_get_sent_msg
57 .. doxygendefine:: MSG_init
58 .. doxygenfunction:: MSG_launch_application
59 .. doxygenfunction:: MSG_main
60 .. doxygenfunction:: MSG_set_function
61
62 Process Management Functions
63 ----------------------------
64
65 This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it.
66
67 .. doxygentypedef:: msg_process_t
68 .. doxygenfunction:: MSG_process_attach
69 .. doxygenfunction:: MSG_process_auto_restart_set
70 .. doxygenfunction:: MSG_process_create
71 .. doxygenfunction:: MSG_process_create_with_arguments
72 .. doxygenfunction:: MSG_process_create_with_environment
73 .. doxygenfunction:: MSG_process_daemonize
74 .. doxygenfunction:: MSG_process_detach
75 .. doxygenfunction:: MSG_processes_as_dynar
76 .. doxygenfunction:: MSG_process_from_PID
77 .. doxygenfunction:: MSG_process_get_data
78 .. doxygenfunction:: MSG_process_get_host
79 .. doxygenfunction:: MSG_process_get_name
80 .. doxygenfunction:: MSG_process_get_number
81 .. doxygenfunction:: MSG_process_get_PID
82 .. doxygenfunction:: MSG_process_get_PPID
83 .. doxygenfunction:: MSG_process_get_properties
84 .. doxygenfunction:: MSG_process_get_property_value
85 .. doxygenfunction:: MSG_process_is_suspended
86 .. doxygenfunction:: MSG_process_join
87 .. doxygenfunction:: MSG_process_kill
88 .. doxygenfunction:: MSG_process_killall
89 .. doxygenfunction:: MSG_process_migrate
90 .. doxygenfunction:: MSG_process_on_exit
91 .. doxygenfunction:: MSG_process_ref
92 .. doxygenfunction:: MSG_process_restart
93 .. doxygenfunction:: MSG_process_resume
94 .. doxygenfunction:: MSG_process_self
95 .. doxygenfunction:: MSG_process_self_name
96 .. doxygenfunction:: MSG_process_self_PID
97 .. doxygenfunction:: MSG_process_self_PPID
98 .. doxygenfunction:: MSG_process_set_data
99 .. doxygenfunction:: MSG_process_set_data_cleanup
100 .. doxygenfunction:: MSG_process_set_kill_time
101 .. doxygenfunction:: MSG_process_sleep
102 .. doxygenfunction:: MSG_process_suspend
103 .. doxygenfunction:: MSG_process_unref
104 .. doxygenfunction:: MSG_process_yield
105
106 Host Management Functions
107 -------------------------
108
109 .. doxygentypedef:: msg_host_t
110 .. doxygenfunction:: MSG_host_by_name
111 .. doxygenfunction:: MSG_get_host_by_name
112 .. doxygenfunction:: MSG_get_host_number
113 .. doxygenfunction:: MSG_host_get_attached_storage_lists
114 .. doxygenfunction:: MSG_host_get_core_number
115 .. doxygenfunction:: MSG_host_get_data
116 .. doxygenfunction:: MSG_host_get_mounted_storage_list
117 .. doxygenfunction:: MSG_host_get_name
118 .. doxygenfunction:: MSG_host_get_nb_pstates
119 .. doxygenfunction:: MSG_host_get_power_peak_at
120 .. doxygenfunction:: MSG_host_get_process_list
121 .. doxygenfunction:: MSG_host_get_properties
122 .. doxygenfunction:: MSG_host_get_property_value
123 .. doxygenfunction:: MSG_host_get_pstate
124 .. doxygenfunction:: MSG_host_get_speed
125 .. doxygenfunction:: MSG_host_is_off
126 .. doxygenfunction:: MSG_host_is_on
127 .. doxygenfunction:: MSG_host_off
128 .. doxygenfunction:: MSG_host_on
129 .. doxygenfunction:: MSG_hosts_as_dynar
130 .. doxygenfunction:: MSG_host_self
131 .. doxygenfunction:: MSG_host_set_data
132 .. doxygenfunction:: MSG_host_set_property_value
133 .. doxygenfunction:: MSG_host_set_pstate
134
135 Task Management Functions
136 -------------------------
137
138 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
139
140 .. doxygentypedef:: msg_task_t
141 .. doxygendefine:: MSG_TASK_UNINITIALIZED
142
143 .. doxygenfunction:: MSG_parallel_task_create
144 .. doxygenfunction:: MSG_parallel_task_execute
145 .. doxygenfunction:: MSG_parallel_task_execute_with_timeout
146 .. doxygenfunction:: MSG_task_cancel
147 .. doxygenfunction:: MSG_task_create
148 .. doxygenfunction:: MSG_task_destroy
149 .. doxygenfunction:: MSG_task_dsend
150 .. doxygenfunction:: MSG_task_dsend_bounded
151 .. doxygenfunction:: MSG_task_execute
152 .. doxygenfunction:: MSG_task_get_bytes_amount
153 .. doxygenfunction:: MSG_task_get_category
154 .. doxygenfunction:: MSG_task_get_data
155 .. doxygenfunction:: MSG_task_get_flops_amount
156 .. doxygenfunction:: MSG_task_get_name
157 .. doxygenfunction:: MSG_task_get_remaining_communication
158 .. doxygenfunction:: MSG_task_get_remaining_work_ratio
159 .. doxygenfunction:: MSG_task_get_sender
160 .. doxygenfunction:: MSG_task_get_source
161 .. doxygenfunction:: MSG_task_irecv
162 .. doxygenfunction:: MSG_task_irecv_bounded
163 .. doxygenfunction:: MSG_task_isend
164 .. doxygenfunction:: MSG_task_isend_bounded
165 .. doxygenfunction:: MSG_task_listen
166 .. doxygenfunction:: MSG_task_listen_from
167 .. doxygenfunction:: MSG_task_receive
168 .. doxygenfunction:: MSG_task_receive_bounded
169 .. doxygenfunction:: MSG_task_receive_ext
170 .. doxygenfunction:: MSG_task_receive_ext_bounded
171 .. doxygenfunction:: MSG_task_receive_with_timeout
172 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
173 .. doxygendefine:: MSG_task_recv
174 .. doxygendefine:: MSG_task_recv_bounded
175 .. doxygenfunction:: MSG_task_send
176 .. doxygenfunction:: MSG_task_send_bounded
177 .. doxygenfunction:: MSG_task_send_with_timeout
178 .. doxygenfunction:: MSG_task_send_with_timeout_bounded
179 .. doxygenfunction:: MSG_task_set_bound
180 .. doxygenfunction:: MSG_task_set_bytes_amount
181 .. doxygenfunction:: MSG_task_set_category
182 .. doxygenfunction:: MSG_task_set_copy_callback
183 .. doxygenfunction:: MSG_task_set_data
184 .. doxygenfunction:: MSG_task_set_flops_amount
185 .. doxygenfunction:: MSG_task_set_name
186 .. doxygenfunction:: MSG_task_set_priority
187
188                    
189 Mailbox Management Functions
190 ----------------------------
191
192 .. doxygenfunction:: MSG_mailbox_set_async
193
194 Communications
195 --------------
196
197 .. doxygentypedef:: msg_comm_t
198
199 .. doxygenfunction:: MSG_comm_destroy
200 .. doxygenfunction:: MSG_comm_get_status
201 .. doxygenfunction:: MSG_comm_get_task
202 .. doxygenfunction:: MSG_comm_test
203 .. doxygenfunction:: MSG_comm_testany
204 .. doxygenfunction:: MSG_comm_wait
205 .. doxygenfunction:: MSG_comm_waitall
206 .. doxygenfunction:: MSG_comm_waitany
207
208 Explicit Synchronization Functions
209 ----------------------------------
210
211 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
212
213 In some situations, these things are very helpful to synchronize processes without message exchanges.
214
215 Barriers
216 ........
217
218 .. doxygentypedef:: msg_bar_t
219 .. doxygenfunction:: MSG_barrier_destroy
220 .. doxygenfunction:: MSG_barrier_init
221 .. doxygenfunction:: MSG_barrier_wait
222
223 Semaphores
224 ..........
225                      
226 .. doxygentypedef:: msg_sem_t
227 .. doxygenfunction:: MSG_sem_acquire
228 .. doxygenfunction:: MSG_sem_acquire_timeout
229 .. doxygenfunction:: MSG_sem_destroy
230 .. doxygenfunction:: MSG_sem_get_capacity
231 .. doxygenfunction:: MSG_sem_init
232 .. doxygenfunction:: MSG_sem_release
233 .. doxygenfunction:: MSG_sem_would_block
234
235 Virtual Machines
236 ----------------
237
238 This interface mimics IaaS clouds.
239 With it, you can create virtual machines to put your processes
240 into, and interact directly with the VMs to manage groups of
241 processes.
242
243 .. doxygentypedef:: msg_vm_t
244 .. doxygenfunction:: MSG_vm_create_core
245 .. doxygenfunction:: MSG_vm_create_multicore
246 .. doxygenfunction:: MSG_vm_destroy
247 .. doxygenfunction:: MSG_vm_get_name
248 .. doxygenfunction:: MSG_vm_get_pm
249 .. doxygenfunction:: MSG_vm_get_ramsize
250 .. doxygenfunction:: MSG_vm_is_created
251 .. doxygenfunction:: MSG_vm_is_running
252 .. doxygenfunction:: MSG_vm_is_suspended
253 .. doxygenfunction:: MSG_vm_resume
254 .. doxygenfunction:: MSG_vm_set_bound
255 .. doxygenfunction:: MSG_vm_set_ramsize
256 .. doxygenfunction:: MSG_vm_shutdown
257 .. doxygenfunction:: MSG_vm_start
258 .. doxygenfunction:: MSG_vm_suspend
259
260 Storage Management Functions
261 ----------------------------
262 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
263
264 .. doxygentypedef:: msg_storage_t
265 .. doxygenfunction:: MSG_storage_get_by_name
266 .. doxygenfunction:: MSG_storage_get_data
267 .. doxygenfunction:: MSG_storage_get_host
268 .. doxygenfunction:: MSG_storage_get_name
269 .. doxygenfunction:: MSG_storage_get_properties
270 .. doxygenfunction:: MSG_storage_get_property_value
271 .. doxygenfunction:: MSG_storage_read
272 .. doxygenfunction:: MSG_storages_as_dynar
273 .. doxygenfunction:: MSG_storage_set_data
274 .. doxygenfunction:: MSG_storage_set_property_value
275 .. doxygenfunction:: MSG_storage_write
276
277 Zone Management Functions
278 -------------------------
279 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
280
281 .. doxygentypedef:: msg_netzone_t
282 .. doxygenfunction:: MSG_zone_get_by_name
283 .. doxygenfunction:: MSG_zone_get_hosts
284 .. doxygenfunction:: MSG_zone_get_name
285 .. doxygenfunction:: MSG_zone_get_property_value
286 .. doxygenfunction:: MSG_zone_get_root
287 .. doxygenfunction:: MSG_zone_get_sons
288 .. doxygenfunction:: MSG_zone_set_property_value