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_off
 115 .. doxygenfunction:: MSG_host_is_on
 116 .. doxygenfunction:: MSG_host_off
 117 .. doxygenfunction:: MSG_host_on
 118 .. doxygenfunction:: MSG_hosts_as_dynar
 119 .. doxygenfunction:: MSG_host_self
 120 .. doxygenfunction:: MSG_host_set_data
 121 .. doxygenfunction:: MSG_host_set_property_value
 122 .. doxygenfunction:: MSG_host_set_pstate
 123
 124 Task Management
 125 ===============
 126
 127 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
 128
 129 .. doxygentypedef:: msg_task_t
 130 .. doxygendefine:: MSG_TASK_UNINITIALIZED
 131
 132 .. doxygenfunction:: MSG_parallel_task_create
 133 .. doxygenfunction:: MSG_parallel_task_execute
 134 .. doxygenfunction:: MSG_parallel_task_execute_with_timeout
 135 .. doxygenfunction:: MSG_task_cancel
 136 .. doxygenfunction:: MSG_task_create
 137 .. doxygenfunction:: MSG_task_destroy
 138 .. doxygenfunction:: MSG_task_dsend
 139 .. doxygenfunction:: MSG_task_dsend_bounded
 140 .. doxygenfunction:: MSG_task_execute
 141 .. doxygenfunction:: MSG_task_get_bytes_amount
 142 .. doxygenfunction:: MSG_task_get_category
 143 .. doxygenfunction:: MSG_task_get_data
 144 .. doxygenfunction:: MSG_task_get_flops_amount
 145 .. doxygenfunction:: MSG_task_get_name
 146 .. doxygenfunction:: MSG_task_get_remaining_communication
 147 .. doxygenfunction:: MSG_task_get_remaining_work_ratio
 148 .. doxygenfunction:: MSG_task_get_sender
 149 .. doxygenfunction:: MSG_task_get_source
 150 .. doxygenfunction:: MSG_task_irecv
 151 .. doxygenfunction:: MSG_task_irecv_bounded
 152 .. doxygenfunction:: MSG_task_isend
 153 .. doxygenfunction:: MSG_task_isend_bounded
 154 .. doxygenfunction:: MSG_task_listen
 155 .. doxygenfunction:: MSG_task_listen_from
 156 .. doxygenfunction:: MSG_task_receive
 157 .. doxygenfunction:: MSG_task_receive_bounded
 158 .. doxygenfunction:: MSG_task_receive_ext
 159 .. doxygenfunction:: MSG_task_receive_ext_bounded
 160 .. doxygenfunction:: MSG_task_receive_with_timeout
 161 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
 162 .. doxygendefine:: MSG_task_recv
 163 .. doxygendefine:: MSG_task_recv_bounded
 164 .. doxygenfunction:: MSG_task_send
 165 .. doxygenfunction:: MSG_task_send_bounded
 166 .. doxygenfunction:: MSG_task_send_with_timeout
 167 .. doxygenfunction:: MSG_task_send_with_timeout_bounded
 168 .. doxygenfunction:: MSG_task_set_bound
 169 .. doxygenfunction:: MSG_task_set_bytes_amount
 170 .. doxygenfunction:: MSG_task_set_category
 171 .. doxygenfunction:: MSG_task_set_copy_callback
 172 .. doxygenfunction:: MSG_task_set_data
 173 .. doxygenfunction:: MSG_task_set_flops_amount
 174 .. doxygenfunction:: MSG_task_set_name
 175 .. doxygenfunction:: MSG_task_set_priority
 176
 177
 178 Mailbox Management
 179 ==================
 180
 181 .. doxygenfunction:: MSG_mailbox_set_async
 182
 183 Communications
 184 ==============
 185
 186 .. doxygentypedef:: msg_comm_t
 187
 188 .. doxygenfunction:: MSG_comm_destroy
 189 .. doxygenfunction:: MSG_comm_get_status
 190 .. doxygenfunction:: MSG_comm_get_task
 191 .. doxygenfunction:: MSG_comm_test
 192 .. doxygenfunction:: MSG_comm_testany
 193 .. doxygenfunction:: MSG_comm_wait
 194 .. doxygenfunction:: MSG_comm_waitall
 195 .. doxygenfunction:: MSG_comm_waitany
 196
 197 Explicit Synchronization
 198 ========================
 199
 200 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
 201
 202 In some situations, these things are very helpful to synchronize processes without message exchanges.
 203
 204 Barriers
 205 --------
 206
 207 .. doxygentypedef:: msg_bar_t
 208 .. doxygenfunction:: MSG_barrier_destroy
 209 .. doxygenfunction:: MSG_barrier_init
 210 .. doxygenfunction:: MSG_barrier_wait
 211
 212 Semaphores
 213 ----------
 214
 215 .. doxygentypedef:: msg_sem_t
 216 .. doxygenfunction:: MSG_sem_acquire
 217 .. doxygenfunction:: MSG_sem_acquire_timeout
 218 .. doxygenfunction:: MSG_sem_destroy
 219 .. doxygenfunction:: MSG_sem_get_capacity
 220 .. doxygenfunction:: MSG_sem_init
 221 .. doxygenfunction:: MSG_sem_release
 222 .. doxygenfunction:: MSG_sem_would_block
 223
 224 Virtual Machines
 225 ================
 226
 227 This interface mimics IaaS clouds.
 228 With it, you can create virtual machines to put your processes
 229 into, and interact directly with the VMs to manage groups of
 230 processes.
 231
 232 .. doxygentypedef:: msg_vm_t
 233 .. doxygenfunction:: MSG_vm_create_core
 234 .. doxygenfunction:: MSG_vm_create_multicore
 235 .. doxygenfunction:: MSG_vm_destroy
 236 .. doxygenfunction:: MSG_vm_get_name
 237 .. doxygenfunction:: MSG_vm_get_pm
 238 .. doxygenfunction:: MSG_vm_get_ramsize
 239 .. doxygenfunction:: MSG_vm_is_created
 240 .. doxygenfunction:: MSG_vm_is_running
 241 .. doxygenfunction:: MSG_vm_is_suspended
 242 .. doxygenfunction:: MSG_vm_resume
 243 .. doxygenfunction:: MSG_vm_set_bound
 244 .. doxygenfunction:: MSG_vm_set_ramsize
 245 .. doxygenfunction:: MSG_vm_shutdown
 246 .. doxygenfunction:: MSG_vm_start
 247 .. doxygenfunction:: MSG_vm_suspend
 248
 249 Storage Management
 250 ==================
 251 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
 252
 253 .. doxygentypedef:: msg_storage_t
 254 .. doxygenfunction:: MSG_storage_get_by_name
 255 .. doxygenfunction:: MSG_storage_get_data
 256 .. doxygenfunction:: MSG_storage_get_host
 257 .. doxygenfunction:: MSG_storage_get_name
 258 .. doxygenfunction:: MSG_storage_get_properties
 259 .. doxygenfunction:: MSG_storage_get_property_value
 260 .. doxygenfunction:: MSG_storage_read
 261 .. doxygenfunction:: MSG_storages_as_dynar
 262 .. doxygenfunction:: MSG_storage_set_data
 263 .. doxygenfunction:: MSG_storage_set_property_value
 264 .. doxygenfunction:: MSG_storage_write
 265
 266 NetZone Management
 267 ==================
 268 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
 269
 270 .. doxygentypedef:: msg_netzone_t
 271 .. doxygenfunction:: MSG_zone_get_by_name
 272 .. doxygenfunction:: MSG_zone_get_hosts
 273 .. doxygenfunction:: MSG_zone_get_name
 274 .. doxygenfunction:: MSG_zone_get_property_value
 275 .. doxygenfunction:: MSG_zone_get_root
 276 .. doxygenfunction:: MSG_zone_get_sons
 277 .. doxygenfunction:: MSG_zone_set_property_value
 278
 279 Java bindings
 280 *************
 281
 282 This section describes jMSG, the Java API to Simgrid. This API mimicks
 283 :ref:`MSG <MSG_doc>`, which is a simple yet somehow realistic interface.
 284 The full reference documentation is provided at the end of this page.
 285
 286 Most of the documentation of the :ref:`MSG API <MSG_doc>` in C applies
 287 directly to the Java bindings (any divergence is seen as a bug that we
 288 should fix). MSG structures are mapped to Java objects as expected,
 289 and the MSG functions are methods in these objects.
 290
 291 Installing the Java bindings
 292 ============================
 293
 294 The easiest is to use a :ref:`precompiled jarfile <install_java_precompiled>`,
 295 but some people may prefer to :ref:`compile it from the sources <install_src>`.
 296
 297
 298 Using the Java bindings
 299 =======================
 300
 301 In most cases, you can use the SimGrid bindings as if it was a Java
 302 library:
 303
 304 .. code-block:: shell
 305
 306    $ javac -classpath .:path/to/simgrid.jar your/java/Code.java
 307    $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code
 308
 309 For example:
 310
 311 .. code-block:: shell
 312
 313    $ cd examples/deprecated/java
 314    $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml
 315
 316 Any SimGrid simulation (java or not) is usually constituted of several
 317 kind of actors or processes (classes extending @c Msg.Process) that
 318 are deployed over the hosts of the virtual platform. So, your code
 319 should declare these actors, plus a Main class in charge of deploying
 320 your actors on the platform. Please refer to the examples for details.
 321
 322 Troubleshooting
 323 ===============
 324
 325 Actually, these bindings are not only implemented in Java. They do use
 326 the C implementation of SimGrid. This should be transparent as this
 327 library is directly included in the ``simgrid.jar`` file but things can
 328 still go wrong is several ways.
 329
 330 Error: library simgrid not found
 331 --------------------------------
 332
 333 This means that the JVM fails to load the native library. If you use a
 334 precompiled jarfile, please report this bug.
 335
 336 If you built it yourself, you can try to use an installed version of
 337 the library instead of the one included in the jar. For that, add the
 338 path to the native library into the ``LD_LIBRARY_PATH`` variable (or in
 339 the ``DYLD_LIBRARY_PATH`` on macOS).
 340
 341 pthread_create failed
 342 ---------------------
 343
 344 You reached the amount of threads that can be run on your system. Try
 345 increasing the thread limits of your operating system.
 346
 347 Other errors
 348 ------------
 349
 350 When using jMSG, your program can crash for 3 main reasons:
 351
 352 - Your Java part is not good: you'll have a good old java exception thrown,
 353   and hence you should be able to correct it by yourself.
 354 - Our java part is not good: you'll also have a java exception thrown, but
 355   we have real doubts this can happen, since the java part is only a JNI
 356   binding. The other option is that it crashed because you used incorrectly
 357   the MSG API, so this means also you should have an MSGException. It means
 358   you should read carefully MSG samples and/or documentation.
 359 - Something has crashed in the C part. Okay, here comes the tricky
 360   thing. It happens mainly for 2 reasons:
 361
 362   - When something goes wrong in your simulation, sometimes the C part stops
 363     because you used SimGrid incorrectly, and JNI bindings are not fond of that.
 364     It means that you'll have something that looks ugly, but you should be able
 365     to identify what's going wrong in your code by carefully reading the whole
 366     error message
 367   - It may happen that the problem comes directly from SimGrid: in this case,
 368     the error should be uglier. In that case, you may submit a bug directly to
 369     SimGrid.
 370
 371 API Reference
 372 =============
 373
 374 Package org.simgrid.msg
 375 -----------------------
 376
 377 .. java:package:: org.simgrid.msg
 378
 379 .. toctree::
 380    :maxdepth: 1
 381
 382    Class org.simgrid.msg.As <java/org/simgrid/msg/As>
 383    Class org.simgrid.msg.Comm <java/org/simgrid/msg/Comm>
 384    Class org.simgrid.msg.File <java/org/simgrid/msg/File>
 385    Class org.simgrid.msg.Host <java/org/simgrid/msg/Host>
 386    Class org.simgrid.msg.HostFailureException <java/org/simgrid/msg/HostFailureException>
 387    Class org.simgrid.msg.HostNotFoundException <java/org/simgrid/msg/HostNotFoundException>
 388    Class org.simgrid.msg.JniException <java/org/simgrid/msg/JniException>
 389    Class org.simgrid.msg.Msg <java/org/simgrid/msg/Msg>
 390    Class org.simgrid.msg.MsgException <java/org/simgrid/msg/MsgException>
 391    Class org.simgrid.msg.Mutex <java/org/simgrid/msg/Mutex>
 392    Class org.simgrid.msg.Process <java/org/simgrid/msg/Process>
 393    Class org.simgrid.msg.ProcessKilledError <java/org/simgrid/msg/ProcessKilledError>
 394    Class org.simgrid.msg.ProcessNotFoundException <java/org/simgrid/msg/ProcessNotFoundException>
 395    Class org.simgrid.msg.RngStream <java/org/simgrid/msg/RngStream>
 396    Class org.simgrid.msg.Semaphore <java/org/simgrid/msg/Semaphore>
 397    Class org.simgrid.msg.Storage <java/org/simgrid/msg/Storage>
 398    Class org.simgrid.msg.StorageNotFoundException <java/org/simgrid/msg/StorageNotFoundException>
 399    Class org.simgrid.msg.Task <java/org/simgrid/msg/Task>
 400    Class org.simgrid.msg.TaskCancelledException <java/org/simgrid/msg/TaskCancelledException>
 401    Class org.simgrid.msg.TimeoutException <java/org/simgrid/msg/TimeoutException>
 402    Class org.simgrid.msg.TransferFailureException <java/org/simgrid/msg/TransferFailureException>
 403    Class org.simgrid.msg.VM <java/org/simgrid/msg/VM>