Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Remove features marked with XBT_ATTRIB_DEPRECATED_v325.
[simgrid.git] / docs / source / app_msg.rst
1 .. _MSG_doc:
2
3 The MSG Interface (legacy interface)
4 ####################################
5
6 .. warning::
7
8    MSG used to be the main API of SimGrid 3, but we are currently in
9    the process of releasing SimGrid 4. So MSG is frozen and will
10    probably never evolve. If you are starting a new project, you
11    should consider S4U instead. Note that the support for MSG will not
12    be removed from SimGrid before 2020 at least.
13
14 MSG is a simple API to write algorithms organized with Concurrent
15 Sequential Processes (CSP) that interact by exchanging messages. It
16 constitutes a convenient simplification of the reality of distributed
17 systems. It can be used to build rather realistic simulations, but
18 remains simple to use: most unpleasant technical elements can be
19 abstracted away rather easily.
20
21 C API reference
22 ***************
23
24 Main MSG Functions
25 ==================
26
27 The basic workflow is the following:
28
29  - Initialize the library with :c:macro:`MSG_init`
30  - Create a platform (usually by parsing a file with :cpp:func:`MSG_create_environment`)
31  - Register the functions that your processes are supposed to run with
32    :cpp:func:`MSG_function_register` (and maybe :cpp:func:`MSG_function_register_default`) 
33  - Launch your processes from a deployment file with :cpp:func:`MSG_launch_application`
34  - Run the simulation with :cpp:func:`MSG_main`
35
36 .. doxygenenum:: msg_error_t
37
38 .. doxygenfunction:: MSG_config
39 .. doxygenfunction:: MSG_create_environment
40 .. doxygenfunction:: MSG_function_register
41 .. doxygenfunction:: MSG_function_register_default
42 .. doxygenfunction:: MSG_get_clock
43 .. doxygenfunction:: MSG_get_sent_msg
44 .. doxygendefine:: MSG_init
45 .. doxygenfunction:: MSG_launch_application
46 .. doxygenfunction:: MSG_main
47 .. doxygenfunction:: MSG_set_function
48
49 Process Management
50 ==================
51
52 This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it.
53
54 .. doxygentypedef:: msg_process_t
55 .. doxygenfunction:: MSG_process_attach
56 .. doxygenfunction:: MSG_process_auto_restart_set
57 .. doxygenfunction:: MSG_process_create
58 .. doxygenfunction:: MSG_process_create_with_arguments
59 .. doxygenfunction:: MSG_process_create_with_environment
60 .. doxygenfunction:: MSG_process_daemonize
61 .. doxygenfunction:: MSG_process_detach
62 .. doxygenfunction:: MSG_processes_as_dynar
63 .. doxygenfunction:: MSG_process_from_PID
64 .. doxygenfunction:: MSG_process_get_data
65 .. doxygenfunction:: MSG_process_get_host
66 .. doxygenfunction:: MSG_process_get_name
67 .. doxygenfunction:: MSG_process_get_number
68 .. doxygenfunction:: MSG_process_get_PID
69 .. doxygenfunction:: MSG_process_get_PPID
70 .. doxygenfunction:: MSG_process_get_properties
71 .. doxygenfunction:: MSG_process_get_property_value
72 .. doxygenfunction:: MSG_process_is_suspended
73 .. doxygenfunction:: MSG_process_join
74 .. doxygenfunction:: MSG_process_kill
75 .. doxygenfunction:: MSG_process_killall
76 .. doxygenfunction:: MSG_process_migrate
77 .. doxygenfunction:: MSG_process_on_exit
78 .. doxygenfunction:: MSG_process_ref
79 .. doxygenfunction:: MSG_process_restart
80 .. doxygenfunction:: MSG_process_resume
81 .. doxygenfunction:: MSG_process_self
82 .. doxygenfunction:: MSG_process_self_name
83 .. doxygenfunction:: MSG_process_self_PID
84 .. doxygenfunction:: MSG_process_self_PPID
85 .. doxygenfunction:: MSG_process_set_data
86 .. doxygenfunction:: MSG_process_set_data_cleanup
87 .. doxygenfunction:: MSG_process_set_kill_time
88 .. doxygenfunction:: MSG_process_sleep
89 .. doxygenfunction:: MSG_process_suspend
90 .. doxygenfunction:: MSG_process_unref
91 .. doxygenfunction:: MSG_process_userdata_init
92 .. doxygenfunction:: MSG_process_yield
93
94 Host Management
95 ===============
96
97 .. doxygentypedef:: msg_host_t
98 .. doxygenfunction:: MSG_host_by_name
99 .. doxygenfunction:: MSG_get_host_by_name
100 .. doxygenfunction:: MSG_get_host_number
101 .. doxygenfunction:: MSG_host_get_attached_storage_lists
102 .. doxygenfunction:: MSG_host_get_core_number
103 .. doxygenfunction:: MSG_host_get_data
104 .. doxygenfunction:: MSG_host_get_mounted_storage_list
105 .. doxygenfunction:: MSG_host_get_name
106 .. doxygenfunction:: MSG_host_get_nb_pstates
107 .. doxygenfunction:: MSG_host_get_load
108 .. doxygenfunction:: MSG_host_get_power_peak_at
109 .. doxygenfunction:: MSG_host_get_process_list
110 .. doxygenfunction:: MSG_host_get_properties
111 .. doxygenfunction:: MSG_host_get_property_value
112 .. doxygenfunction:: MSG_host_get_pstate
113 .. doxygenfunction:: MSG_host_get_speed
114 .. doxygenfunction:: MSG_host_is_on
115 .. doxygenfunction:: MSG_host_off
116 .. doxygenfunction:: MSG_host_on
117 .. doxygenfunction:: MSG_hosts_as_dynar
118 .. doxygenfunction:: MSG_host_self
119 .. doxygenfunction:: MSG_host_set_data
120 .. doxygenfunction:: MSG_host_set_property_value
121 .. doxygenfunction:: MSG_host_set_pstate
122
123 Task Management
124 ===============
125
126 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
127
128 .. doxygentypedef:: msg_task_t
129 .. doxygendefine:: MSG_TASK_UNINITIALIZED
130
131 .. doxygenfunction:: MSG_parallel_task_create
132 .. doxygenfunction:: MSG_parallel_task_execute
133 .. doxygenfunction:: MSG_parallel_task_execute_with_timeout
134 .. doxygenfunction:: MSG_task_cancel
135 .. doxygenfunction:: MSG_task_create
136 .. doxygenfunction:: MSG_task_destroy
137 .. doxygenfunction:: MSG_task_dsend
138 .. doxygenfunction:: MSG_task_dsend_bounded
139 .. doxygenfunction:: MSG_task_execute
140 .. doxygenfunction:: MSG_task_get_bytes_amount
141 .. doxygenfunction:: MSG_task_get_category
142 .. doxygenfunction:: MSG_task_get_data
143 .. doxygenfunction:: MSG_task_get_flops_amount
144 .. doxygenfunction:: MSG_task_get_name
145 .. doxygenfunction:: MSG_task_get_remaining_communication
146 .. doxygenfunction:: MSG_task_get_remaining_work_ratio
147 .. doxygenfunction:: MSG_task_get_sender
148 .. doxygenfunction:: MSG_task_get_source
149 .. doxygenfunction:: MSG_task_irecv
150 .. doxygenfunction:: MSG_task_irecv_bounded
151 .. doxygenfunction:: MSG_task_isend
152 .. doxygenfunction:: MSG_task_isend_bounded
153 .. doxygenfunction:: MSG_task_listen
154 .. doxygenfunction:: MSG_task_listen_from
155 .. doxygenfunction:: MSG_task_receive
156 .. doxygenfunction:: MSG_task_receive_bounded
157 .. doxygenfunction:: MSG_task_receive_ext_bounded
158 .. doxygenfunction:: MSG_task_receive_with_timeout
159 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
160 .. doxygendefine:: MSG_task_recv
161 .. doxygendefine:: MSG_task_recv_bounded
162 .. doxygenfunction:: MSG_task_send
163 .. doxygenfunction:: MSG_task_send_bounded
164 .. doxygenfunction:: MSG_task_send_with_timeout
165 .. doxygenfunction:: MSG_task_send_with_timeout_bounded
166 .. doxygenfunction:: MSG_task_set_bound
167 .. doxygenfunction:: MSG_task_set_bytes_amount
168 .. doxygenfunction:: MSG_task_set_category
169 .. doxygenfunction:: MSG_task_set_data
170 .. doxygenfunction:: MSG_task_set_flops_amount
171 .. doxygenfunction:: MSG_task_set_name
172 .. doxygenfunction:: MSG_task_set_priority
173
174                    
175 Mailbox Management
176 ==================
177
178 .. doxygenfunction:: MSG_mailbox_set_async
179
180 Communications
181 ==============
182
183 .. doxygentypedef:: msg_comm_t
184
185 .. doxygenfunction:: MSG_comm_destroy
186 .. doxygenfunction:: MSG_comm_get_status
187 .. doxygenfunction:: MSG_comm_get_task
188 .. doxygenfunction:: MSG_comm_test
189 .. doxygenfunction:: MSG_comm_testany
190 .. doxygenfunction:: MSG_comm_wait
191 .. doxygenfunction:: MSG_comm_waitall
192 .. doxygenfunction:: MSG_comm_waitany
193
194 Explicit Synchronization
195 ========================
196
197 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
198
199 In some situations, these things are very helpful to synchronize processes without message exchanges.
200
201 Barriers
202 --------
203
204 .. doxygentypedef:: msg_bar_t
205 .. doxygenfunction:: MSG_barrier_destroy
206 .. doxygenfunction:: MSG_barrier_init
207 .. doxygenfunction:: MSG_barrier_wait
208
209 Semaphores
210 ----------
211                      
212 .. doxygentypedef:: msg_sem_t
213 .. doxygenfunction:: MSG_sem_acquire
214 .. doxygenfunction:: MSG_sem_acquire_timeout
215 .. doxygenfunction:: MSG_sem_destroy
216 .. doxygenfunction:: MSG_sem_get_capacity
217 .. doxygenfunction:: MSG_sem_init
218 .. doxygenfunction:: MSG_sem_release
219 .. doxygenfunction:: MSG_sem_would_block
220
221 Virtual Machines
222 ================
223
224 This interface mimics IaaS clouds.
225 With it, you can create virtual machines to put your processes
226 into, and interact directly with the VMs to manage groups of
227 processes.
228
229 .. doxygentypedef:: msg_vm_t
230 .. doxygenfunction:: MSG_vm_create_core
231 .. doxygenfunction:: MSG_vm_create_multicore
232 .. doxygenfunction:: MSG_vm_destroy
233 .. doxygenfunction:: MSG_vm_get_name
234 .. doxygenfunction:: MSG_vm_get_pm
235 .. doxygenfunction:: MSG_vm_get_ramsize
236 .. doxygenfunction:: MSG_vm_is_created
237 .. doxygenfunction:: MSG_vm_is_running
238 .. doxygenfunction:: MSG_vm_is_suspended
239 .. doxygenfunction:: MSG_vm_resume
240 .. doxygenfunction:: MSG_vm_set_bound
241 .. doxygenfunction:: MSG_vm_set_ramsize
242 .. doxygenfunction:: MSG_vm_shutdown
243 .. doxygenfunction:: MSG_vm_start
244 .. doxygenfunction:: MSG_vm_suspend
245
246 Storage Management
247 ==================
248 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
249
250 .. doxygentypedef:: msg_storage_t
251 .. doxygenfunction:: MSG_storage_get_by_name
252 .. doxygenfunction:: MSG_storage_get_data
253 .. doxygenfunction:: MSG_storage_get_host
254 .. doxygenfunction:: MSG_storage_get_name
255 .. doxygenfunction:: MSG_storage_get_properties
256 .. doxygenfunction:: MSG_storage_get_property_value
257 .. doxygenfunction:: MSG_storage_read
258 .. doxygenfunction:: MSG_storages_as_dynar
259 .. doxygenfunction:: MSG_storage_set_data
260 .. doxygenfunction:: MSG_storage_set_property_value
261 .. doxygenfunction:: MSG_storage_write
262
263 NetZone Management
264 ==================
265 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
266
267 .. doxygentypedef:: msg_netzone_t
268 .. doxygenfunction:: MSG_zone_get_by_name
269 .. doxygenfunction:: MSG_zone_get_hosts
270 .. doxygenfunction:: MSG_zone_get_name
271 .. doxygenfunction:: MSG_zone_get_property_value
272 .. doxygenfunction:: MSG_zone_get_root
273 .. doxygenfunction:: MSG_zone_get_sons
274 .. doxygenfunction:: MSG_zone_set_property_value
275
276 Java bindings
277 *************
278
279 This section describes jMSG, the Java API to Simgrid. This API mimicks 
280 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
281 The full reference documentation is provided at the end of this page.
282
283 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
284 directly to the Java bindings (any divergence is seen as a bug that we
285 should fix). MSG structures are mapped to Java objects as expected,
286 and the MSG functions are methods in these objects.
287
288 Installing the Java bindings
289 ============================
290
291 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
292 but some people may prefer to :ref:`compile it from the sources <install_src>`.
293
294
295 Using the Java bindings
296 =======================
297
298 In most cases, you can use the SimGrid bindings as if it was a Java
299 library:
300
301 .. code-block:: shell
302
303    $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
304    $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
305
306 For example:
307
308 .. code-block:: shell
309
310    $ cd examples/deprecated/java
311    $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml 
312
313 Any SimGrid simulation (java or not) is usually constituted of several
314 kind of actors or processes (classes extending @c Msg.Process) that
315 are deployed over the hosts of the virtual platform. So, your code
316 should declare these actors, plus a Main class in charge of deploying
317 your actors on the platform. Please refer to the examples for details.
318
319 Troubleshooting
320 ===============
321
322 Actually, these bindings are not only implemented in Java. They do use
323 the C implementation of SimGrid. This should be transparent as this
324 library is directly included in the ``simgrid.jar`` file but things can
325 still go wrong is several ways.
326
327 Error: library simgrid not found
328 --------------------------------
329
330 This means that the JVM fails to load the native library. If you use a
331 precompiled jarfile, please report this bug.
332
333 If you built it yourself, you can try to use an installed version of
334 the library instead of the one included in the jar. For that, add the
335 path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
336 the ``DYLD_LIBRARY_PATH`` on macOS).
337
338 pthread_create failed
339 ---------------------
340
341 You reached the amount of threads that can be run on your system. Try
342 increasing the thread limits of your operating system.
343
344 Other errors
345 ------------
346
347 When using jMSG, your program can crash for 3 main reasons:
348
349 - Your Java part is not good: you'll have a good old java exception thrown,
350   and hence you should be able to correct it by yourself.
351 - Our java part is not good: you'll also have a java exception thrown, but
352   we have real doubts this can happen, since the java part is only a JNI
353   binding. The other option is that it crashed because you used incorrectly
354   the MSG API, so this means also you should have an MSGException. It means
355   you should read carefully MSG samples and/or documentation.
356 - Something has crashed in the C part. Okay, here comes the tricky
357   thing. It happens mainly for 2 reasons:
358   
359   - When something goes wrong in your simulation, sometimes the C part stops
360     because you used SimGrid incorrectly, and JNI bindings are not fond of that.
361     It means that you'll have something that looks ugly, but you should be able
362     to identify what's going wrong in your code by carefully reading the whole
363     error message
364   - It may happen that the problem comes directly from SimGrid: in this case,
365     the error should be uglier. In that case, you may submit a bug directly to
366     SimGrid.
367
368 API Reference
369 =============
370
371 Package org.simgrid.msg
372 -----------------------
373
374 .. java:package:: org.simgrid.msg
375
376 .. toctree::
377    :maxdepth: 1
378
379    Class org.simgrid.msg.As <java/org/simgrid/msg/As>
380    Class org.simgrid.msg.Comm <java/org/simgrid/msg/Comm>
381    Class org.simgrid.msg.File <java/org/simgrid/msg/File>
382    Class org.simgrid.msg.Host <java/org/simgrid/msg/Host>
383    Class org.simgrid.msg.HostFailureException <java/org/simgrid/msg/HostFailureException>
384    Class org.simgrid.msg.HostNotFoundException <java/org/simgrid/msg/HostNotFoundException>
385    Class org.simgrid.msg.JniException <java/org/simgrid/msg/JniException>
386    Class org.simgrid.msg.Msg <java/org/simgrid/msg/Msg>
387    Class org.simgrid.msg.MsgException <java/org/simgrid/msg/MsgException>
388    Class org.simgrid.msg.Mutex <java/org/simgrid/msg/Mutex>
389    Class org.simgrid.msg.Process <java/org/simgrid/msg/Process>
390    Class org.simgrid.msg.ProcessKilledError <java/org/simgrid/msg/ProcessKilledError>
391    Class org.simgrid.msg.ProcessNotFoundException <java/org/simgrid/msg/ProcessNotFoundException>
392    Class org.simgrid.msg.RngStream <java/org/simgrid/msg/RngStream>
393    Class org.simgrid.msg.Semaphore <java/org/simgrid/msg/Semaphore>
394    Class org.simgrid.msg.Storage <java/org/simgrid/msg/Storage>
395    Class org.simgrid.msg.StorageNotFoundException <java/org/simgrid/msg/StorageNotFoundException>
396    Class org.simgrid.msg.Task <java/org/simgrid/msg/Task>
397    Class org.simgrid.msg.TaskCancelledException <java/org/simgrid/msg/TaskCancelledException>
398    Class org.simgrid.msg.TimeoutException <java/org/simgrid/msg/TimeoutException>
399    Class org.simgrid.msg.TransferFailureException <java/org/simgrid/msg/TransferFailureException>
400    Class org.simgrid.msg.VM <java/org/simgrid/msg/VM>