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