3 The MSG Interface (legacy interface)
4 ####################################
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.
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.
27 The basic workflow is the following:
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`
36 .. doxygenenum:: msg_error_t
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
51 This describes the process structure :cpp:type:`msg_process_t` and the functions for managing it.
53 .. doxygentypedef:: msg_process_t
54 .. doxygenfunction:: MSG_process_attach
55 .. doxygenfunction:: MSG_process_auto_restart_set
56 .. doxygenfunction:: MSG_process_create
57 .. doxygenfunction:: MSG_process_create_with_arguments
58 .. doxygenfunction:: MSG_process_create_with_environment
59 .. doxygenfunction:: MSG_process_daemonize
60 .. doxygenfunction:: MSG_process_detach
61 .. doxygenfunction:: MSG_processes_as_dynar
62 .. doxygenfunction:: MSG_process_from_PID
63 .. doxygenfunction:: MSG_process_get_data
64 .. doxygenfunction:: MSG_process_get_host
65 .. doxygenfunction:: MSG_process_get_name
66 .. doxygenfunction:: MSG_process_get_number
67 .. doxygenfunction:: MSG_process_get_PID
68 .. doxygenfunction:: MSG_process_get_PPID
69 .. doxygenfunction:: MSG_process_get_properties
70 .. doxygenfunction:: MSG_process_get_property_value
71 .. doxygenfunction:: MSG_process_is_suspended
72 .. doxygenfunction:: MSG_process_join
73 .. doxygenfunction:: MSG_process_kill
74 .. doxygenfunction:: MSG_process_killall
75 .. doxygenfunction:: MSG_process_migrate
76 .. doxygenfunction:: MSG_process_on_exit
77 .. doxygenfunction:: MSG_process_ref
78 .. doxygenfunction:: MSG_process_restart
79 .. doxygenfunction:: MSG_process_resume
80 .. doxygenfunction:: MSG_process_self
81 .. doxygenfunction:: MSG_process_self_name
82 .. doxygenfunction:: MSG_process_self_PID
83 .. doxygenfunction:: MSG_process_self_PPID
84 .. doxygenfunction:: MSG_process_set_data
85 .. doxygenfunction:: MSG_process_set_data_cleanup
86 .. doxygenfunction:: MSG_process_set_kill_time
87 .. doxygenfunction:: MSG_process_sleep
88 .. doxygenfunction:: MSG_process_suspend
89 .. doxygenfunction:: MSG_process_unref
90 .. doxygenfunction:: MSG_process_yield
95 .. doxygentypedef:: msg_host_t
96 .. doxygenfunction:: MSG_host_by_name
97 .. doxygenfunction:: MSG_get_host_by_name
98 .. doxygenfunction:: MSG_get_host_number
99 .. doxygenfunction:: MSG_host_get_attached_storage_lists
100 .. doxygenfunction:: MSG_host_get_core_number
101 .. doxygenfunction:: MSG_host_get_data
102 .. doxygenfunction:: MSG_host_get_mounted_storage_list
103 .. doxygenfunction:: MSG_host_get_name
104 .. doxygenfunction:: MSG_host_get_nb_pstates
105 .. doxygenfunction:: MSG_host_get_load
106 .. doxygenfunction:: MSG_host_get_power_peak_at
107 .. doxygenfunction:: MSG_host_get_process_list
108 .. doxygenfunction:: MSG_host_get_properties
109 .. doxygenfunction:: MSG_host_get_property_value
110 .. doxygenfunction:: MSG_host_get_pstate
111 .. doxygenfunction:: MSG_host_get_speed
112 .. doxygenfunction:: MSG_host_is_on
113 .. doxygenfunction:: MSG_host_off
114 .. doxygenfunction:: MSG_host_on
115 .. doxygenfunction:: MSG_hosts_as_dynar
116 .. doxygenfunction:: MSG_host_self
117 .. doxygenfunction:: MSG_host_set_data
118 .. doxygenfunction:: MSG_host_set_property_value
119 .. doxygenfunction:: MSG_host_set_pstate
124 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
126 .. doxygentypedef:: msg_task_t
127 .. doxygendefine:: MSG_TASK_UNINITIALIZED
129 .. doxygenfunction:: MSG_parallel_task_create
130 .. doxygenfunction:: MSG_parallel_task_execute
131 .. doxygenfunction:: MSG_parallel_task_execute_with_timeout
132 .. doxygenfunction:: MSG_task_cancel
133 .. doxygenfunction:: MSG_task_create
134 .. doxygenfunction:: MSG_task_destroy
135 .. doxygenfunction:: MSG_task_dsend
136 .. doxygenfunction:: MSG_task_dsend_bounded
137 .. doxygenfunction:: MSG_task_execute
138 .. doxygenfunction:: MSG_task_get_bytes_amount
139 .. doxygenfunction:: MSG_task_get_category
140 .. doxygenfunction:: MSG_task_get_data
141 .. doxygenfunction:: MSG_task_get_flops_amount
142 .. doxygenfunction:: MSG_task_get_name
143 .. doxygenfunction:: MSG_task_get_remaining_communication
144 .. doxygenfunction:: MSG_task_get_remaining_work_ratio
145 .. doxygenfunction:: MSG_task_get_sender
146 .. doxygenfunction:: MSG_task_get_source
147 .. doxygenfunction:: MSG_task_irecv
148 .. doxygenfunction:: MSG_task_irecv_bounded
149 .. doxygenfunction:: MSG_task_isend
150 .. doxygenfunction:: MSG_task_isend_bounded
151 .. doxygenfunction:: MSG_task_listen
152 .. doxygenfunction:: MSG_task_listen_from
153 .. doxygenfunction:: MSG_task_receive
154 .. doxygenfunction:: MSG_task_receive_bounded
155 .. doxygenfunction:: MSG_task_receive_with_timeout
156 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
157 .. doxygendefine:: MSG_task_recv
158 .. doxygendefine:: MSG_task_recv_bounded
159 .. doxygenfunction:: MSG_task_send
160 .. doxygenfunction:: MSG_task_send_bounded
161 .. doxygenfunction:: MSG_task_send_with_timeout
162 .. doxygenfunction:: MSG_task_send_with_timeout_bounded
163 .. doxygenfunction:: MSG_task_set_bound
164 .. doxygenfunction:: MSG_task_set_bytes_amount
165 .. doxygenfunction:: MSG_task_set_category
166 .. doxygenfunction:: MSG_task_set_data
167 .. doxygenfunction:: MSG_task_set_flops_amount
168 .. doxygenfunction:: MSG_task_set_name
169 .. doxygenfunction:: MSG_task_set_priority
175 .. doxygenfunction:: MSG_mailbox_set_async
180 .. doxygentypedef:: msg_comm_t
182 .. doxygenfunction:: MSG_comm_destroy
183 .. doxygenfunction:: MSG_comm_get_status
184 .. doxygenfunction:: MSG_comm_get_task
185 .. doxygenfunction:: MSG_comm_test
186 .. doxygenfunction:: MSG_comm_testany
187 .. doxygenfunction:: MSG_comm_wait
188 .. doxygenfunction:: MSG_comm_waitall
189 .. doxygenfunction:: MSG_comm_waitany
191 Explicit Synchronization
192 ========================
194 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
196 In some situations, these things are very helpful to synchronize processes without message exchanges.
201 .. doxygentypedef:: msg_bar_t
202 .. doxygenfunction:: MSG_barrier_destroy
203 .. doxygenfunction:: MSG_barrier_init
204 .. doxygenfunction:: MSG_barrier_wait
209 .. doxygentypedef:: msg_sem_t
210 .. doxygenfunction:: MSG_sem_acquire
211 .. doxygenfunction:: MSG_sem_acquire_timeout
212 .. doxygenfunction:: MSG_sem_destroy
213 .. doxygenfunction:: MSG_sem_get_capacity
214 .. doxygenfunction:: MSG_sem_init
215 .. doxygenfunction:: MSG_sem_release
216 .. doxygenfunction:: MSG_sem_would_block
221 This interface mimics IaaS clouds.
222 With it, you can create virtual machines to put your processes
223 into, and interact directly with the VMs to manage groups of
226 .. doxygentypedef:: msg_vm_t
227 .. doxygenfunction:: MSG_vm_create_core
228 .. doxygenfunction:: MSG_vm_create_multicore
229 .. doxygenfunction:: MSG_vm_destroy
230 .. doxygenfunction:: MSG_vm_get_name
231 .. doxygenfunction:: MSG_vm_get_pm
232 .. doxygenfunction:: MSG_vm_get_ramsize
233 .. doxygenfunction:: MSG_vm_is_created
234 .. doxygenfunction:: MSG_vm_is_running
235 .. doxygenfunction:: MSG_vm_is_suspended
236 .. doxygenfunction:: MSG_vm_resume
237 .. doxygenfunction:: MSG_vm_set_bound
238 .. doxygenfunction:: MSG_vm_set_ramsize
239 .. doxygenfunction:: MSG_vm_shutdown
240 .. doxygenfunction:: MSG_vm_start
241 .. doxygenfunction:: MSG_vm_suspend
245 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
247 .. doxygentypedef:: msg_storage_t
248 .. doxygenfunction:: MSG_storage_get_by_name
249 .. doxygenfunction:: MSG_storage_get_data
250 .. doxygenfunction:: MSG_storage_get_host
251 .. doxygenfunction:: MSG_storage_get_name
252 .. doxygenfunction:: MSG_storage_get_properties
253 .. doxygenfunction:: MSG_storage_get_property_value
254 .. doxygenfunction:: MSG_storage_read
255 .. doxygenfunction:: MSG_storages_as_dynar
256 .. doxygenfunction:: MSG_storage_set_data
257 .. doxygenfunction:: MSG_storage_set_property_value
258 .. doxygenfunction:: MSG_storage_write
262 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
264 .. doxygentypedef:: msg_netzone_t
265 .. doxygenfunction:: MSG_zone_get_by_name
266 .. doxygenfunction:: MSG_zone_get_hosts
267 .. doxygenfunction:: MSG_zone_get_name
268 .. doxygenfunction:: MSG_zone_get_property_value
269 .. doxygenfunction:: MSG_zone_get_root
270 .. doxygenfunction:: MSG_zone_get_sons
271 .. doxygenfunction:: MSG_zone_set_property_value
276 This section describes jMSG, the Java API to Simgrid. This API mimicks
277 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
278 The full reference documentation is provided at the end of this page.
280 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
281 directly to the Java bindings (any divergence is seen as a bug that we
282 should fix). MSG structures are mapped to Java objects as expected,
283 and the MSG functions are methods in these objects.
285 Installing the Java bindings
286 ============================
288 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
289 but some people may prefer to :ref:`compile it from the sources <install_src>`.
292 Using the Java bindings
293 =======================
295 In most cases, you can use the SimGrid bindings as if it was a Java
298 .. code-block:: shell
300 $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
301 $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
305 .. code-block:: shell
307 $ cd examples/deprecated/java
308 $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml
310 Any SimGrid simulation (java or not) is usually constituted of several
311 kind of actors or processes (classes extending @c Msg.Process) that
312 are deployed over the hosts of the virtual platform. So, your code
313 should declare these actors, plus a Main class in charge of deploying
314 your actors on the platform. Please refer to the examples for details.
319 Actually, these bindings are not only implemented in Java. They do use
320 the C implementation of SimGrid. This should be transparent as this
321 library is directly included in the ``simgrid.jar`` file but things can
322 still go wrong is several ways.
324 Error: library simgrid not found
325 --------------------------------
327 This means that the JVM fails to load the native library. If you use a
328 precompiled jarfile, please report this bug.
330 If you built it yourself, you can try to use an installed version of
331 the library instead of the one included in the jar. For that, add the
332 path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
333 the ``DYLD_LIBRARY_PATH`` on macOS).
335 pthread_create failed
336 ---------------------
338 You reached the amount of threads that can be run on your system. Try
339 increasing the thread limits of your operating system.
344 When using jMSG, your program can crash for 3 main reasons:
346 - Your Java part is not good: you'll have a good old java exception thrown,
347 and hence you should be able to correct it by yourself.
348 - Our java part is not good: you'll also have a java exception thrown, but
349 we have real doubts this can happen, since the java part is only a JNI
350 binding. The other option is that it crashed because you used incorrectly
351 the MSG API, so this means also you should have an MSGException. It means
352 you should read carefully MSG samples and/or documentation.
353 - Something has crashed in the C part. Okay, here comes the tricky
354 thing. It happens mainly for 2 reasons:
356 - When something goes wrong in your simulation, sometimes the C part stops
357 because you used SimGrid incorrectly, and JNI bindings are not fond of that.
358 It means that you'll have something that looks ugly, but you should be able
359 to identify what's going wrong in your code by carefully reading the whole
361 - It may happen that the problem comes directly from SimGrid: in this case,
362 the error should be uglier. In that case, you may submit a bug directly to
368 Package org.simgrid.msg
369 -----------------------
371 .. java:package:: org.simgrid.msg
376 Class org.simgrid.msg.As <java/org/simgrid/msg/As>
377 Class org.simgrid.msg.Comm <java/org/simgrid/msg/Comm>
378 Class org.simgrid.msg.File <java/org/simgrid/msg/File>
379 Class org.simgrid.msg.Host <java/org/simgrid/msg/Host>
380 Class org.simgrid.msg.HostFailureException <java/org/simgrid/msg/HostFailureException>
381 Class org.simgrid.msg.HostNotFoundException <java/org/simgrid/msg/HostNotFoundException>
382 Class org.simgrid.msg.JniException <java/org/simgrid/msg/JniException>
383 Class org.simgrid.msg.Msg <java/org/simgrid/msg/Msg>
384 Class org.simgrid.msg.MsgException <java/org/simgrid/msg/MsgException>
385 Class org.simgrid.msg.Mutex <java/org/simgrid/msg/Mutex>
386 Class org.simgrid.msg.Process <java/org/simgrid/msg/Process>
387 Class org.simgrid.msg.ProcessKilledError <java/org/simgrid/msg/ProcessKilledError>
388 Class org.simgrid.msg.ProcessNotFoundException <java/org/simgrid/msg/ProcessNotFoundException>
389 Class org.simgrid.msg.Semaphore <java/org/simgrid/msg/Semaphore>
390 Class org.simgrid.msg.Storage <java/org/simgrid/msg/Storage>
391 Class org.simgrid.msg.StorageNotFoundException <java/org/simgrid/msg/StorageNotFoundException>
392 Class org.simgrid.msg.Task <java/org/simgrid/msg/Task>
393 Class org.simgrid.msg.TaskCancelledException <java/org/simgrid/msg/TaskCancelledException>
394 Class org.simgrid.msg.TimeoutException <java/org/simgrid/msg/TimeoutException>
395 Class org.simgrid.msg.TransferFailureException <java/org/simgrid/msg/TransferFailureException>
396 Class org.simgrid.msg.VM <java/org/simgrid/msg/VM>