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_create_from_stdfunc
  74 .. doxygenfunction:: MSG_process_daemonize
  75 .. doxygenfunction:: MSG_process_detach
  76 .. doxygenfunction:: MSG_processes_as_dynar
  77 .. doxygenfunction:: MSG_process_from_PID
  78 .. doxygenfunction:: MSG_process_get_data
  79 .. doxygenfunction:: MSG_process_get_host
  80 .. doxygenfunction:: MSG_process_get_name
  81 .. doxygenfunction:: MSG_process_get_number
  82 .. doxygenfunction:: MSG_process_get_PID
  83 .. doxygenfunction:: MSG_process_get_PPID
  84 .. doxygenfunction:: MSG_process_get_properties
  85 .. doxygenfunction:: MSG_process_get_property_value
  86 .. doxygenfunction:: MSG_process_get_smx_ctx
  87 .. doxygenfunction:: MSG_process_is_suspended
  88 .. doxygenfunction:: MSG_process_join
  89 .. doxygenfunction:: MSG_process_kill
  90 .. doxygenfunction:: MSG_process_killall
  91 .. doxygenfunction:: MSG_process_migrate
  92 .. doxygenfunction:: MSG_process_on_exit
  93 .. doxygenfunction:: MSG_process_ref
  94 .. doxygenfunction:: MSG_process_restart
  95 .. doxygenfunction:: MSG_process_resume
  96 .. doxygenfunction:: MSG_process_self
  97 .. doxygenfunction:: MSG_process_self_name
  98 .. doxygenfunction:: MSG_process_self_PID
  99 .. doxygenfunction:: MSG_process_self_PPID
 100 .. doxygenfunction:: MSG_process_set_data
 101 .. doxygenfunction:: MSG_process_set_data_cleanup
 102 .. doxygenfunction:: MSG_process_set_kill_time
 103 .. doxygenfunction:: MSG_process_sleep
 104 .. doxygenfunction:: MSG_process_suspend
 105 .. doxygenfunction:: MSG_process_unref
 106 .. doxygenfunction:: MSG_process_yield
 107
 108 Host Management Functions
 109 -------------------------
 110
 111 .. doxygentypedef:: msg_host_t
 112 .. doxygenfunction:: MSG_host_by_name
 113 .. doxygenfunction:: MSG_get_host_by_name
 114 .. doxygenfunction:: MSG_get_host_number
 115 .. doxygenfunction:: MSG_host_get_attached_storage_lists
 116 .. doxygenfunction:: MSG_host_get_core_number
 117 .. doxygenfunction:: MSG_host_get_data
 118 .. doxygenfunction:: MSG_host_get_mounted_storage_list
 119 .. doxygenfunction:: MSG_host_get_name
 120 .. doxygenfunction:: MSG_host_get_nb_pstates
 121 .. doxygenfunction:: MSG_host_get_power_peak_at
 122 .. doxygenfunction:: MSG_host_get_process_list
 123 .. doxygenfunction:: MSG_host_get_properties
 124 .. doxygenfunction:: MSG_host_get_property_value
 125 .. doxygenfunction:: MSG_host_get_pstate
 126 .. doxygenfunction:: MSG_host_get_speed
 127 .. doxygenfunction:: MSG_host_is_off
 128 .. doxygenfunction:: MSG_host_is_on
 129 .. doxygenfunction:: MSG_host_off
 130 .. doxygenfunction:: MSG_host_on
 131 .. doxygenfunction:: MSG_hosts_as_dynar
 132 .. doxygenfunction:: MSG_host_self
 133 .. doxygenfunction:: MSG_host_set_data
 134 .. doxygenfunction:: MSG_host_set_property_value
 135 .. doxygenfunction:: MSG_host_set_pstate
 136
 137 Task Management Functions
 138 -------------------------
 139
 140 Task structure of MSG :cpp:type:`msg_task_t` and associated functions.
 141
 142 .. doxygentypedef:: msg_task_t
 143 .. doxygendefine:: MSG_TASK_UNINITIALIZED
 144
 145 .. doxygenfunction:: MSG_parallel_task_create
 146 .. doxygenfunction:: MSG_parallel_task_execute
 147 .. doxygenfunction:: MSG_parallel_task_execute_with_timeout
 148 .. doxygenfunction:: MSG_task_cancel
 149 .. doxygenfunction:: MSG_task_create
 150 .. doxygenfunction:: MSG_task_destroy
 151 .. doxygenfunction:: MSG_task_dsend
 152 .. doxygenfunction:: MSG_task_dsend_bounded
 153 .. doxygenfunction:: MSG_task_execute
 154 .. doxygenfunction:: MSG_task_get_bytes_amount
 155 .. doxygenfunction:: MSG_task_get_category
 156 .. doxygenfunction:: MSG_task_get_data
 157 .. doxygenfunction:: MSG_task_get_flops_amount
 158 .. doxygenfunction:: MSG_task_get_name
 159 .. doxygenfunction:: MSG_task_get_remaining_communication
 160 .. doxygenfunction:: MSG_task_get_remaining_work_ratio
 161 .. doxygenfunction:: MSG_task_get_sender
 162 .. doxygenfunction:: MSG_task_get_source
 163 .. doxygenfunction:: MSG_task_irecv
 164 .. doxygenfunction:: MSG_task_irecv_bounded
 165 .. doxygenfunction:: MSG_task_isend
 166 .. doxygenfunction:: MSG_task_isend_bounded
 167 .. doxygenfunction:: MSG_task_listen
 168 .. doxygenfunction:: MSG_task_listen_from
 169 .. doxygenfunction:: MSG_task_receive
 170 .. doxygenfunction:: MSG_task_receive_bounded
 171 .. doxygenfunction:: MSG_task_receive_ext
 172 .. doxygenfunction:: MSG_task_receive_ext_bounded
 173 .. doxygenfunction:: MSG_task_receive_with_timeout
 174 .. doxygenfunction:: MSG_task_receive_with_timeout_bounded
 175 .. doxygenfunction:: MSG_task_recv
 176 .. doxygenfunction:: MSG_task_recv_bounded
 177 .. doxygenfunction:: MSG_task_send
 178 .. doxygenfunction:: MSG_task_send_bounded
 179 .. doxygenfunction:: MSG_task_send_with_timeout
 180 .. doxygenfunction:: MSG_task_send_with_timeout_bounded
 181 .. doxygenfunction:: MSG_task_set_bound
 182 .. doxygenfunction:: MSG_task_set_bytes_amount
 183 .. doxygenfunction:: MSG_task_set_category
 184 .. doxygenfunction:: MSG_task_set_copy_callback
 185 .. doxygenfunction:: MSG_task_set_data
 186 .. doxygenfunction:: MSG_task_set_flops_amount
 187 .. doxygenfunction:: MSG_task_set_name
 188 .. doxygenfunction:: MSG_task_set_priority
 189
 190
 191 Mailbox Management Functions
 192 ----------------------------
 193
 194 .. doxygenfunction:: MSG_mailbox_set_async
 195
 196 Communications
 197 --------------
 198
 199 .. doxygentypedef:: msg_comm_t
 200
 201 .. doxygenfunction:: MSG_comm_destroy
 202 .. doxygenfunction:: MSG_comm_get_status
 203 .. doxygenfunction:: MSG_comm_get_task
 204 .. doxygenfunction:: MSG_comm_test
 205 .. doxygenfunction:: MSG_comm_testany
 206 .. doxygenfunction:: MSG_comm_wait
 207 .. doxygenfunction:: MSG_comm_waitall
 208 .. doxygenfunction:: MSG_comm_waitany
 209
 210 Explicit Synchronization Functions
 211 ----------------------------------
 212
 213 Explicit synchronization mechanisms: semaphores (:cpp:type:`msg_sem_t`) and friends.
 214
 215 In some situations, these things are very helpful to synchronize processes without message exchanges.
 216
 217 Barriers
 218 ........
 219
 220 .. doxygentypedef:: msg_bar_t
 221 .. doxygenfunction:: MSG_barrier_destroy
 222 .. doxygenfunction:: MSG_barrier_init
 223 .. doxygenfunction:: MSG_barrier_wait
 224
 225 Semaphores
 226 ..........
 227
 228 .. doxygentypedef:: msg_sem_t
 229 .. doxygenfunction:: MSG_sem_acquire
 230 .. doxygenfunction:: MSG_sem_acquire_timeout
 231 .. doxygenfunction:: MSG_sem_destroy
 232 .. doxygenfunction:: MSG_sem_get_capacity
 233 .. doxygenfunction:: MSG_sem_init
 234 .. doxygenfunction:: MSG_sem_release
 235 .. doxygenfunction:: MSG_sem_would_block
 236
 237 Virtual Machines
 238 ----------------
 239
 240 This interface mimics IaaS clouds.
 241 With it, you can create virtual machines to put your processes
 242 into, and interact directly with the VMs to manage groups of
 243 processes.
 244
 245 .. doxygentypedef:: msg_vm_t
 246 .. doxygenfunction:: MSG_vm_create
 247 .. doxygenfunction:: MSG_vm_create_core
 248 .. doxygenfunction:: MSG_vm_create_multicore
 249 .. doxygenfunction:: MSG_vm_destroy
 250 .. doxygenfunction:: MSG_vm_get_name
 251 .. doxygenfunction:: MSG_vm_get_pm
 252 .. doxygenfunction:: MSG_vm_get_ramsize
 253 .. doxygenfunction:: MSG_vm_is_created
 254 .. doxygenfunction:: MSG_vm_is_running
 255 .. doxygenfunction:: MSG_vm_is_suspended
 256 .. doxygenfunction:: MSG_vm_resume
 257 .. doxygenfunction:: MSG_vm_set_bound
 258 .. doxygenfunction:: MSG_vm_set_ramsize
 259 .. doxygenfunction:: MSG_vm_shutdown
 260 .. doxygenfunction:: MSG_vm_start
 261 .. doxygenfunction:: MSG_vm_suspend
 262
 263 Storage Management Functions
 264 ----------------------------
 265 Storage structure of MSG (:cpp:type:`msg_storage_t`) and associated functions, inspired from POSIX.
 266
 267 .. doxygentypedef:: msg_storage_t
 268 .. doxygenfunction:: MSG_storage_get_by_name
 269 .. doxygenfunction:: MSG_storage_get_data
 270 .. doxygenfunction:: MSG_storage_get_host
 271 .. doxygenfunction:: MSG_storage_get_name
 272 .. doxygenfunction:: MSG_storage_get_properties
 273 .. doxygenfunction:: MSG_storage_get_property_value
 274 .. doxygenfunction:: MSG_storage_read
 275 .. doxygenfunction:: MSG_storages_as_dynar
 276 .. doxygenfunction:: MSG_storage_set_data
 277 .. doxygenfunction:: MSG_storage_set_property_value
 278 .. doxygenfunction:: MSG_storage_write
 279
 280 Zone Management Functions
 281 -------------------------
 282 Network Zone (:cpp:class:`msg_file_t`) and associated functions.
 283
 284 .. doxygentypedef:: msg_netzone_t
 285 .. doxygenfunction:: MSG_zone_get_by_name
 286 .. doxygenfunction:: MSG_zone_get_hosts
 287 .. doxygenfunction:: MSG_zone_get_name
 288 .. doxygenfunction:: MSG_zone_get_property_value
 289 .. doxygenfunction:: MSG_zone_get_root
 290 .. doxygenfunction:: MSG_zone_get_sons
 291 .. doxygenfunction:: MSG_zone_set_property_value