docs/source/app_s4u.rst

   1 .. _S4U_doc:
   2
   3 The S4U Interface
   4 #################
   5
   6 .. raw:: html
   7
   8    <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
   9    <script>
  10    window.onload=function() { // Wait for the SVG to be loaded before changing it
  11      var elem=document.querySelector("#TOC").contentDocument.getElementById("ActorBox")
  12      elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
  13    }
  14    </script>
  15    <br/>
  16    <br/>
  17
  18 The S4U interface (SimGrid for you) mixes the full power of SimGrid
  19 with the full power of C++. This is the preferred interface to describe
  20 abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar
  21 settings.
  22
  23 Since v3.33 (Spring 2023), S4U is the main interface of SimGrid for algorithms.
  24 It is feature complete, but may still evolve slightly in future releases.
  25 When this happens, compiling your code will produce deprecation warnings for 4
  26 releases (one year) before the removal of the old symbols.
  27
  28 .. _S4U_main_concepts:
  29
  30 Main Concepts
  31 *************
  32
  33 A typical SimGrid simulation is composed of several |API_s4u_Actors|_, that
  34 execute user-provided functions. The actors have to explicitly use the
  35 S4U interface to express their :ref:`computation <API_s4u_Exec>`,
  36 :ref:`communication <API_s4u_Comm>`, :ref:`disk usage <API_s4u_Io>`,
  37 and other |API_s4u_Activities|_, so that they get reflected within the
  38 simulator. These activities take place on resources such as |API_s4u_Hosts|_,
  39 |API_s4u_Links|_, and |API_s4u_Disks|_. SimGrid predicts the time taken by each
  40 activity and orchestrates the actors accordingly, waiting for the
  41 completion of these activities.
  42
  43
  44 When **communicating**, data is not directly sent to other actors but
  45 posted onto a |API_s4u_Mailbox|_ that serves as a rendezvous point between
  46 communicating actors. This means that you don't need to know who you
  47 are talking to, you just put your communication `Put` request in a
  48 mailbox, and it will be matched with a complementary `Get`
  49 request.  Alternatively, actors can interact through **classical
  50 synchronization mechanisms** such as |API_s4u_Barrier|_, |API_s4u_Semaphore|_,
  51 |API_s4u_Mutex|_, and |API_s4u_ConditionVariable|_.
  52
  53 Each actor is located on a simulated |API_s4u_Host|_. Each host is located
  54 in a |API_s4u_NetZone|_, that knows the networking path between one
  55 resource to another. Each NetZone is included in another one, forming
  56 a tree of NetZones which root zone contains the whole platform. The
  57 actors can also be located on a |API_s4U_VirtualMachine|_ that may
  58 restrict the activities it contains to a limited amount of cores.
  59 Virtual machines can also be migrated between hosts.
  60
  61 The :ref:`simgrid::s4u::this_actor <API_s4u_this_actor>` namespace
  62 provides many helper functions to simplify the code of actors.
  63
  64 .. rst-class:: compact-list
  65
  66    - **Simulation Elements**
  67
  68       - :ref:`class Actor <API_s4u_Actor>`: Active entities executing your application.
  69       - :ref:`class Engine <API_s4u_Engine>`: Simulation engine (singleton).
  70       - :ref:`class Mailbox <API_s4u_Mailbox>`: Communication rendezvous, with which actors meet each other.
  71
  72    - **Resources**
  73
  74       - :ref:`class Disk <API_s4u_Disk>`: Resource on which actors can write and read data.
  75       - :ref:`class Host <API_s4u_Host>`: Actor location, providing computational power.
  76       - :ref:`class Link <API_s4u_Link>`: Interconnecting hosts.
  77       - :ref:`class NetZone <API_s4u_NetZone>`: Sub-region of the platform, containing resources (Hosts, Links, etc).
  78       - :ref:`class VirtualMachine <API_s4u_VirtualMachine>`: Execution containers that can be moved between Hosts.
  79
  80    - **Activities** (:ref:`class Activity <API_s4u_Activity>`): The things that actors can do on resources.
  81
  82       - :ref:`class Comm <API_s4u_Comm>`: Communication activity, started on Mailboxes and consuming links.
  83       - :ref:`class Exec <API_s4u_Exec>`: Computation activity, started on Host and consuming CPU resources.
  84       - :ref:`class Io <API_s4u_Io>`: I/O activity, started on and consuming disks.
  85
  86    - **Synchronization Objects**: Classical IPC that actors can use
  87
  88       - :ref:`class Barrier <API_s4u_Barrier>`
  89       - :ref:`class ConditionVariable <API_s4u_ConditionVariable>`
  90       - :ref:`class Mutex <API_s4u_Mutex>`
  91       - :ref:`class Semaphore <API_s4u_Semaphore>`
  92
  93 .. |API_s4u_Actors| replace:: **Actors**
  94 .. _API_s4u_Actors: #api-s4u-actor
  95
  96 .. |API_s4u_Activities| replace:: **Activities**
  97 .. _API_s4u_Activities: #api-s4u-activity
  98
  99 .. |API_s4u_Tasks| replace:: **Tasks**
 100 .. _API_s4u_Tasks: #api-s4u-task
 101
 102 .. |API_s4u_Hosts| replace:: **Hosts**
 103 .. _API_s4u_Hosts: #api-s4u-host
 104
 105 .. |API_s4u_Links| replace:: **Links**
 106 .. _API_s4u_Links: #api-s4u-link
 107
 108 .. |API_s4u_Disks| replace:: **Disks**
 109 .. _API_s4u_Disks: #api-s4u-disk
 110
 111 .. |API_s4u_VirtualMachine| replace:: **VirtualMachines**
 112
 113 .. |API_s4u_Host| replace:: **Host**
 114
 115 .. |API_s4u_Mailbox| replace:: **Mailbox**
 116
 117 .. |API_s4u_Mailboxes| replace:: **Mailboxes**
 118 .. _API_s4u_Mailboxes: #s4u-mailbox
 119
 120 .. |API_s4u_NetZone| replace:: **NetZone**
 121
 122 .. |API_s4u_Barrier| replace:: **Barrier**
 123
 124 .. |API_s4u_Semaphore| replace:: **Semaphore**
 125
 126 .. |API_s4u_ConditionVariable| replace:: **ConditionVariable**
 127
 128 .. |API_s4u_Mutex| replace:: **Mutex**
 129
 130 .. _s4u_Activities:
 131
 132 Activities
 133 **********
 134
 135 Activities represent the actions that consume a resource, such as a
 136 :ref:`Comm <API_s4u_Comm>` that consumes the *transmitting power* of
 137 :ref:`Link <API_s4u_Link>` resources, or an :ref:`Exec <API_s4u_Exec>`
 138 that consumes the *computing power* of :ref:`Host <API_s4u_Host>` resources.
 139 See also the :ref:`full API <API_s4u_Activity>` below.
 140
 141 =======================
 142 Asynchronous Activities
 143 =======================
 144
 145 Every activity can be either **blocking** or **asynchronous**. For
 146 example, :cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>`
 147 and :cpp:func:`s4u::Mailbox::get() <simgrid::s4u::Mailbox::get>`
 148 create blocking communications: the actor is blocked until the
 149 completion of that communication. Asynchronous communications do not
 150 block the actor during their execution but progress on their own.
 151
 152 Once your asynchronous activity is started, you can test for its
 153 completion using :cpp:func:`s4u::Activity::test() <simgrid::s4u::Activity::test>`.
 154 This function returns ``true`` if the activity is completed already.
 155 You can also use :cpp:func:`s4u::Activity::wait() <simgrid::s4u::Activity::wait>`
 156 to block until the completion of the activity. To wait for at most a given amount of time,
 157 use  :cpp:func:`s4u::Activity::wait_for() <simgrid::s4u::Activity::wait_for>`.
 158 Finally, to wait at most until a specified time limit, use
 159 :cpp:func:`s4u::Activity::wait_until() <simgrid::s4u::Activity::wait_until>`.
 160
 161 Every kind of activity can be asynchronous.
 162 :ref:`s4u::CommPtr <API_s4u_Comm>` are created with :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
 163 :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`;
 164 :ref:`s4u::IoPtr <API_s4u_Io>` are created with :cpp:func:`s4u::Disk::read_async() <simgrid::s4u::Disk::read_async>` and
 165 :cpp:func:`s4u::Disk::write_async() <simgrid::s4u::Disk::write_async>`; and
 166 :ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
 167 :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
 168 In the future, it will become possible to have asynchronous IPC such as asynchronous mutex lock requests.
 169
 170 The following example shows how to have several concurrent
 171 communications ongoing.  First, you have to declare a vector in which
 172 we will store the ongoing communications. It is also useful to have a
 173 vector of mailboxes.
 174
 175 .. literalinclude:: ../../examples/cpp/comm-waitall/s4u-comm-waitall.cpp
 176    :language: c++
 177    :start-after: init-begin
 178    :end-before: init-end
 179    :dedent: 2
 180
 181 Then, you start all the communications that should occur concurrently with
 182 :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.
 183 Finally, the actor waits for the completion of all of them at once
 184 with :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.
 185
 186 .. literalinclude:: ../../examples/cpp/comm-waitall/s4u-comm-waitall.cpp
 187    :language: c++
 188    :start-after: put-begin
 189    :end-before: put-end
 190    :dedent: 2
 191
 192 =====================
 193 Activities Life Cycle
 194 =====================
 195
 196 Sometimes, you want to change the setting of an activity before it even starts.
 197
 198 .. todo:: write this section
 199
 200 =====================
 201 Repeatable Activities
 202 =====================
 203
 204 In order to simulate the execution of Dataflow applications, we introduced the
 205 concept of |API_s4u_Tasks|, that can be seen as repeatable activities. A Dataflow
 206 is defined as a graph of |API_s4u_Tasks|, where each |API_s4u_Tasks| has a set of
 207 successors and predecessors. When a |API_s4u_Tasks| ends it sends a token to each
 208 of its successors. Each |API_s4u_Tasks| has to receive a token from each of its
 209 predecessor to start. Tokens can carry any user-defined data.
 210
 211 |API_s4u_Tasks| are composed of several instances: a dispatcher, a collector, and
 212 instance_0 to instance_n. The dispatcher rely on a load balancing function to select
 213 the next instance to fire. Once this instance finishes it fires the collector.
 214
 215 Each instance of an |API_s4u_ExecTask| can be placed on a different host.
 216 |API_s4u_Comm| activities are automatically created when an instance triggers
 217 another instance on a different host. Each instance has its own parallelism degree
 218 to scale horizontally on several cores.
 219
 220 To initiate the execution of a Dataflow, it is possible to some make
 221 |API_s4u_Tasks| fire one or more activities without waiting for any token with the
 222 :cpp:func:`s4u::Task::enqueue_firings() <simgrid::s4u::Task::enqueue_firings>`
 223 function.
 224
 225 The parameters of Tasks can be redefined at runtime by attaching
 226 callbacks to the
 227 :cpp:func:`s4u::Task::on_this_start <simgrid::s4u::Task::on_this_start>`
 228 and
 229 :cpp:func:`s4u::Task::on_this_completion <simgrid::s4u::Task::on_this_completion>`
 230 signals. The former is triggered by instances others than the dispatcher and the collector,
 231 and the latter is triggered by the collector.
 232
 233
 234
 235 .. _s4u_mailbox:
 236
 237 Mailboxes
 238 *********
 239
 240 Please also refer to the :ref:`API reference for s4u::Mailbox
 241 <API_s4u_Mailbox>`.
 242
 243 ===================
 244 What are Mailboxes?
 245 ===================
 246
 247 |API_s4u_Mailboxes|_ are rendezvous points for network communications,
 248 similar to URLs on which you could post and retrieve data. Actually,
 249 the mailboxes are not involved in the communication once it starts,
 250 but only to find the contact with which you want to communicate.
 251
 252 They are similar to many common things: The phone number, which allows
 253 the caller to find the receiver. The Twitter hashtag, which helps
 254 senders and receivers to find each other. In TCP, the pair
 255 ``{host name, host port}`` to which you can connect to find your peer.
 256 In HTTP, URLs through which the clients can connect to the servers.
 257 In ZeroMQ, the queues are used to match senders and receivers.
 258
 259 One big difference with most of these systems is that no actor is the
 260 exclusive owner of a mailbox, neither in sending nor in receiving.
 261 Many actors can send into and/or receive from the same mailbox.  TCP
 262 socket ports for example are shared on the sender side but exclusive
 263 on the receiver side (only one process can receive from a given socket
 264 at a given point of time).
 265
 266 A big difference with TCP sockets or MPI communications is that
 267 communications do not start right away after a
 268 :cpp:func:`Mailbox::put() <simgrid::s4u::Mailbox::put>`, but wait
 269 for the corresponding :cpp:func:`Mailbox::get() <simgrid::s4u::Mailbox::get>`.
 270 You can change this by :ref:`declaring a receiving actor <s4u_receiving_actor>`.
 271
 272 A big difference with Twitter hashtags is that SimGrid does not
 273 offer easy support to broadcast a given message to many
 274 receivers. So that would be like a Twitter tag where each message
 275 is consumed by the first receiver.
 276
 277 A big difference with the ZeroMQ queues is that you cannot filter
 278 on the data you want to get from the mailbox. To model such settings
 279 in SimGrid, you'd have one mailbox per potential topic, and subscribe
 280 to each topic individually with a
 281 :cpp:func:`get_async() <simgrid::s4u::Mailbox::get_async>` on each mailbox.
 282 Then, use :cpp:func:`Comm::wait_any() <simgrid::s4u::Comm::wait_any>`
 283 to get the first message on any of the mailboxes you are subscribed to.
 284
 285 The mailboxes are not located on the network, and you can access
 286 them without any latency. The network delays are only related to the
 287 location of the sender and receiver once the match between them is
 288 done on the mailbox. This is just like the phone number that you
 289 can use locally, and the geographical distance only comes into play
 290 once you start the communication by dialing this number.
 291
 292 =====================
 293 How to use Mailboxes?
 294 =====================
 295
 296 You can retrieve any existing mailbox from its name (which is a
 297 unique string, just like a Twitter tag). This results in a
 298 versatile tool that can be used to build many different
 299 situations.
 300
 301 To model classical socket communications, use "hostname:port" as
 302 mailbox names, and make sure that only one actor reads into a given
 303 mailbox. This does not make it easy to build a perfectly realistic
 304 model of the TCP sockets, but in most cases, this system is too
 305 cumbersome for your simulations anyway. You probably want something
 306 simpler, that turns out to be easy to build with the mailboxes.
 307
 308 Many SimGrid examples use a sort of yellow page system where the
 309 mailbox names are the name of the service (such as "worker",
 310 "master", or "reducer"). That way, you don't have to know where your
 311 peer is located to contact it. You don't even need its name. Its
 312 function is enough for that. This also gives you some sort of load
 313 balancing for free if more than one actor pulls from the mailbox:
 314 the first actor that can deal with the request will handle it.
 315
 316 =========================================
 317 How are put() and get() requests matched?
 318 =========================================
 319
 320 The matching algorithm simple: first come, first serve. When a new
 321 send arrives, it matches the oldest enqueued receive. If no receive is
 322 currently enqueued, then the incoming send is enqueued. As you can
 323 see, the mailbox cannot contain both send and receive requests: all
 324 enqueued requests must be of the same sort.
 325
 326 .. _s4u_receiving_actor:
 327
 328 ===========================
 329 Declaring a Receiving Actor
 330 ===========================
 331
 332 The last twist is that by default in the simulator, the data starts
 333 to be exchanged only when both the sender and the receiver are
 334 announced (it waits until both :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
 335 and :cpp:func:`get() <simgrid::s4u::Mailbox::get()>` are posted).
 336 In TCP, since you establish connections beforehand, the data starts to
 337 flow as soon as the sender posts it, even if the receiver did not post
 338 its :cpp:func:`put() <simgrid::s4u::Mailbox::put()>` yet.
 339
 340 To model this in SimGrid, you can declare a specific receiver to a
 341 given mailbox (with the function
 342 :cpp:func:`set_receiver() <simgrid::s4u::Mailbox::set_receiver()>`).
 343 That way, any :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
 344 posted to that mailbox will start as soon as possible, and the data
 345 will already be there on the receiver host when the receiver actor
 346 posts its :cpp:func:`get() <simgrid::s4u::Mailbox::get()>`
 347
 348 Note that being permanent receivers of a mailbox prevents actors to be
 349 garbage-collected. If your simulation creates many short-lived actors
 350 that are marked as permanent receiver, you should call
 351 ``mailbox->set_receiver(nullptr)`` by the end of the actors so that their
 352 memory gets properly reclaimed. This call should be at the end of the
 353 actor's function, not in an on_exit callback.
 354
 355 ===============================
 356 Communicating without Mailboxes
 357 ===============================
 358
 359 Sometimes you don't want to simulate communications between actors as
 360 allowed by mailboxes, but you want to create a direct communication
 361 between two arbitrary hosts. This can arise when you write a
 362 high-level model of a centralized scheduler, or when you model direct
 363 communications such as one-sided communications in MPI or remote
 364 memory direct access in PGAS.
 365
 366 For that, :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`
 367 simulates a direct communication between the two specified hosts. No
 368 mailbox is used, and there is no rendezvous between actors. You can
 369 freely mix such direct communications and rendezvous-based
 370 communications. Alternatively, :cpp:func:`Comm::sendto_init()
 371 <simgrid::s4u::Comm::sendto_init()>` and
 372 :cpp:func:`Comm::sendto_async() <simgrid::s4u::Comm::sendto_async()>`
 373 create asynchronous direct communications.
 374
 375 .. _s4u_raii:
 376
 377 Memory Management
 378 *****************
 379
 380 For sake of simplicity, we use `RAII
 381 <https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
 382 for many classes in S4U. This is an idiom where resources are automatically
 383 managed through the context. Provided that you never manipulate
 384 objects of type Foo directly but always FooPtr references (which are
 385 defined as `boost::intrusive_ptr
 386 <http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
 387 <Foo>), you will never have to explicitly release the resource that
 388 you use nor to free the memory of unused objects.
 389 Here is a little example:
 390
 391 .. code-block:: cpp
 392
 393    void myFunc()
 394    {
 395      simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
 396
 397      mutex->lock();   // use the mutex as a simple reference
 398      //  bla bla
 399      mutex->unlock();
 400
 401    } // The mutex gets automatically freed because the only existing reference gets out of scope
 402
 403 Note that Mailboxes, Hosts, and Links are not handled through smart
 404 pointers (yet?). This means that it is currently impossible to destroy a
 405 mailbox or a link. You can still destroy a host (but probably
 406 shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
 407
 408 API Reference
 409 *************
 410
 411 .. _API_s4u_simulation_object:
 412
 413 ==================
 414 Simulation objects
 415 ==================
 416
 417 .. _API_s4u_Actor:
 418
 419 ==============
 420 ⁣  class Actor
 421 ==============
 422
 423 .. tabs::
 424
 425    .. group-tab:: C++
 426
 427       .. doxygenclass:: simgrid::s4u::Actor
 428
 429       .. doxygentypedef:: aid_t
 430
 431
 432    .. group-tab:: Python
 433
 434       .. autoclass:: simgrid.Actor
 435
 436 Basic management
 437 ----------------
 438
 439 .. tabs::
 440
 441    .. group-tab:: C++
 442
 443       .. code:: C++
 444
 445          #include <simgrid/s4u/Actor.hpp>
 446
 447       .. doxygentypedef:: ActorPtr
 448
 449    .. group-tab:: Python
 450
 451       .. code:: Python
 452
 453          from simgrid import Actor
 454
 455    .. group-tab:: C
 456
 457       .. code:: C
 458
 459          #include <simgrid/actor.h>
 460
 461       .. doxygentypedef:: sg_actor_t
 462       .. doxygentypedef:: const_sg_actor_t
 463       .. doxygenfunction:: sg_actor_ref
 464       .. doxygenfunction:: sg_actor_unref
 465
 466
 467 Creating actors
 468 ---------------
 469
 470 See also :ref:`the relevant example <s4u_ex_actors_create>`.
 471
 472 .. tabs::
 473
 474    .. group-tab:: C++
 475
 476       .. doxygenfunction:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code)
 477       .. doxygenfunction:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code)
 478       .. doxygenfunction:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args)
 479       .. doxygenfunction:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector< std::string > args)
 480
 481       .. doxygenfunction:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host)
 482       .. doxygenfunction:: simgrid::s4u::Actor::start(const std::function< void()> &code)
 483       .. doxygenfunction:: simgrid::s4u::Actor::set_stacksize
 484
 485    .. group-tab:: Python
 486
 487       .. automethod:: simgrid.Actor.create
 488
 489    .. group-tab:: C
 490
 491       .. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, char *const *argv)
 492       .. doxygenfunction:: sg_actor_init(const char *name, sg_host_t host)
 493       .. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char *const *argv)
 494       .. doxygenfunction:: sg_actor_set_stacksize
 495
 496       .. doxygenfunction:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties)
 497       .. doxygenfunction:: sg_actor_detach()
 498
 499 Retrieving actors
 500 -----------------
 501
 502 .. tabs::
 503
 504    .. group-tab:: C++
 505
 506       .. doxygenfunction:: simgrid::s4u::Actor::by_pid(aid_t pid)
 507       .. doxygenfunction:: simgrid::s4u::Actor::self()
 508
 509    .. group-tab:: Python
 510
 511       .. automethod:: simgrid.Actor.by_pid
 512       .. automethod:: simgrid.Actor.self
 513
 514    .. group-tab:: C
 515
 516       .. doxygenfunction:: sg_actor_by_pid(aid_t pid)
 517       .. doxygenfunction:: sg_actor_self()
 518       .. doxygenfunction:: sg_actor_list()
 519
 520 Querying info
 521 -------------
 522
 523 .. tabs::
 524
 525    .. group-tab:: C++
 526
 527       .. doxygenfunction:: simgrid::s4u::Actor::get_cname
 528       .. doxygenfunction:: simgrid::s4u::Actor::get_name
 529       .. doxygenfunction:: simgrid::s4u::Actor::get_pid
 530       .. doxygenfunction:: simgrid::s4u::Actor::get_ppid
 531       .. doxygenfunction:: simgrid::s4u::Actor::get_properties() const
 532       .. doxygenfunction:: simgrid::s4u::Actor::get_property(const std::string &key) const
 533       .. doxygenfunction:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value)
 534
 535       .. doxygenfunction:: simgrid::s4u::Actor::get_host
 536       .. doxygenfunction:: simgrid::s4u::Actor::set_host
 537
 538       .. doxygenfunction:: simgrid::s4u::Actor::get_refcount
 539       .. doxygenfunction:: simgrid::s4u::Actor::get_impl
 540
 541    .. group-tab:: Python
 542
 543       .. autoattribute:: simgrid.Actor.name
 544       .. autoattribute:: simgrid.Actor.host
 545       .. autoattribute:: simgrid.Actor.pid
 546       .. autoattribute:: simgrid.Actor.ppid
 547
 548    .. group-tab:: C
 549
 550       .. doxygenfunction:: sg_actor_get_name(const_sg_actor_t actor)
 551       .. doxygenfunction:: sg_actor_get_pid(const_sg_actor_t actor)
 552       .. doxygenfunction:: sg_actor_get_ppid(const_sg_actor_t actor)
 553       .. doxygenfunction:: sg_actor_get_properties(const_sg_actor_t actor)
 554       .. doxygenfunction:: sg_actor_get_property_value(const_sg_actor_t actor, const char *name)
 555
 556       .. doxygenfunction:: sg_actor_get_host(const_sg_actor_t actor)
 557       .. doxygenfunction:: sg_actor_set_host(sg_actor_t actor, sg_host_t host)
 558
 559       .. doxygenfunction:: sg_actor_get_data(const_sg_actor_t actor)
 560       .. doxygenfunction:: sg_actor_set_data(sg_actor_t actor, void *userdata)
 561
 562 Suspending and resuming actors
 563 ------------------------------
 564
 565 .. tabs::
 566
 567    .. group-tab:: C++
 568
 569       .. doxygenfunction:: simgrid::s4u::Actor::suspend()
 570       .. doxygenfunction:: simgrid::s4u::Actor::resume()
 571       .. doxygenfunction:: simgrid::s4u::Actor::is_suspended
 572
 573    .. group-tab:: Python
 574
 575       .. automethod:: simgrid.Actor.resume
 576       .. automethod:: simgrid.Actor.suspend
 577       .. automethod:: simgrid.Actor.is_suspended
 578
 579    .. group-tab:: C
 580
 581       .. doxygenfunction:: sg_actor_suspend(sg_actor_t actor)
 582       .. doxygenfunction:: sg_actor_resume(sg_actor_t actor)
 583       .. doxygenfunction:: sg_actor_is_suspended(const_sg_actor_t actor)
 584
 585 Specifying when actors should terminate
 586 ---------------------------------------
 587
 588 .. tabs::
 589
 590    .. group-tab:: C++
 591
 592       .. doxygenfunction:: simgrid::s4u::Actor::kill()
 593       .. doxygenfunction:: simgrid::s4u::Actor::kill_all()
 594       .. doxygenfunction:: simgrid::s4u::Actor::set_kill_time(double time)
 595       .. doxygenfunction:: simgrid::s4u::Actor::get_kill_time
 596
 597       .. doxygenfunction:: simgrid::s4u::Actor::restart()
 598       .. doxygenfunction:: simgrid::s4u::Actor::daemonize()
 599       .. doxygenfunction:: simgrid::s4u::Actor::is_daemon
 600
 601    .. group-tab:: Python
 602
 603       .. automethod:: simgrid.Actor.kill
 604       .. automethod:: simgrid.Actor.kill_all
 605
 606       .. automethod:: simgrid.Actor.daemonize
 607       .. automethod:: simgrid.Actor.is_daemon
 608
 609    .. group-tab:: C
 610
 611       .. doxygenfunction:: sg_actor_kill(sg_actor_t actor)
 612       .. doxygenfunction:: sg_actor_kill_all()
 613       .. doxygenfunction:: sg_actor_set_kill_time(sg_actor_t actor, double kill_time)
 614
 615       .. doxygenfunction:: sg_actor_restart(sg_actor_t actor)
 616       .. doxygenfunction:: sg_actor_daemonize(sg_actor_t actor)
 617       .. doxygenfunction:: sg_actor_is_daemon
 618
 619 .. _API_s4u_Actor_end:
 620
 621 Reacting to the end of actors
 622 -----------------------------
 623
 624 .. tabs::
 625
 626    .. group-tab:: C++
 627
 628       .. doxygenfunction:: simgrid::s4u::Actor::on_exit
 629       .. doxygenfunction:: simgrid::s4u::Actor::join() const
 630       .. doxygenfunction:: simgrid::s4u::Actor::join(double timeout) const
 631       .. doxygenfunction:: simgrid::s4u::Actor::set_auto_restart(bool autorestart)
 632       .. doxygenfunction:: simgrid::s4u::Actor::get_restart_count
 633
 634    .. group-tab:: Python
 635
 636       .. automethod:: simgrid.Actor.join
 637
 638    .. group-tab:: C
 639
 640       .. doxygenfunction:: sg_actor_on_exit
 641       .. doxygenfunction:: sg_actor_join(const_sg_actor_t actor, double timeout)
 642       .. doxygenfunction:: sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart)
 643
 644 Signals
 645 -------
 646
 647 .. tabs::
 648
 649    .. group-tab:: C++
 650
 651       .. doxygenfunction:: simgrid::s4u::Actor::on_creation_cb
 652       .. doxygenfunction:: simgrid::s4u::Actor::on_suspend_cb
 653       .. doxygenfunction:: simgrid::s4u::Actor::on_this_suspend_cb
 654       .. doxygenfunction:: simgrid::s4u::Actor::on_host_change_cb
 655       .. doxygenfunction:: simgrid::s4u::Actor::on_this_host_change_cb
 656       .. doxygenfunction:: simgrid::s4u::Actor::on_resume_cb
 657       .. doxygenfunction:: simgrid::s4u::Actor::on_this_resume_cb
 658       .. doxygenfunction:: simgrid::s4u::Actor::on_sleep_cb
 659       .. doxygenfunction:: simgrid::s4u::Actor::on_this_sleep_cb
 660       .. doxygenfunction:: simgrid::s4u::Actor::on_wake_up_cb
 661       .. doxygenfunction:: simgrid::s4u::Actor::on_this_wake_up_cb
 662       .. doxygenfunction:: simgrid::s4u::Actor::on_termination_cb
 663       .. doxygenfunction:: simgrid::s4u::Actor::on_this_termination_cb
 664       .. doxygenfunction:: simgrid::s4u::Actor::on_destruction_cb
 665       .. doxygenfunction:: simgrid::s4u::Actor::on_this_destruction_cb
 666
 667 .. _API_s4u_this_actor:
 668
 669 ====================
 670 ⁣  The current actor
 671 ====================
 672
 673 These functions can be used in your user code to interact with the actor
 674 currently running (the one retrieved with :cpp:func:`simgrid::s4u::Actor::self`).
 675 Using these functions can greatly improve the code readability.
 676
 677 Querying info
 678 -------------
 679
 680 .. tabs::
 681
 682    .. group-tab:: C++
 683
 684       .. doxygenfunction:: simgrid::s4u::this_actor::get_cname()
 685       .. doxygenfunction:: simgrid::s4u::this_actor::get_name()
 686       .. doxygenfunction:: simgrid::s4u::this_actor::get_pid()
 687       .. doxygenfunction:: simgrid::s4u::this_actor::get_ppid()
 688       .. doxygenfunction:: simgrid::s4u::this_actor::is_maestro()
 689
 690       .. doxygenfunction:: simgrid::s4u::this_actor::get_host()
 691       .. doxygenfunction:: simgrid::s4u::this_actor::set_host(Host *new_host)
 692
 693    .. group-tab:: Python
 694
 695       .. autofunction:: simgrid.this_actor.get_host
 696       .. autofunction:: simgrid.this_actor.set_host
 697
 698       .. autofunction:: simgrid.this_actor.get_pid
 699       .. autofunction:: simgrid.this_actor.get_ppid
 700
 701    .. group-tab:: C
 702
 703       .. doxygenfunction:: sg_actor_self_get_data()
 704       .. doxygenfunction:: sg_actor_self_set_data(void *data)
 705       .. doxygenfunction:: sg_actor_self_get_name()
 706       .. doxygenfunction:: sg_actor_self_get_pid()
 707       .. doxygenfunction:: sg_actor_self_get_ppid()
 708       .. doxygenfunction:: sg_host_self()
 709       .. doxygenfunction:: sg_host_self_get_name()
 710
 711 Suspending and resuming
 712 -----------------------
 713
 714 .. tabs::
 715
 716    .. group-tab:: C++
 717
 718       .. doxygenfunction:: simgrid::s4u::this_actor::suspend()
 719       .. doxygenfunction:: simgrid::s4u::this_actor::yield()
 720
 721    .. group-tab:: Python
 722
 723       .. autofunction:: simgrid.this_actor.suspend
 724       .. autofunction:: simgrid.this_actor.yield_
 725
 726    .. group-tab:: C
 727
 728       .. doxygenfunction:: sg_actor_yield()
 729
 730 Logging messages
 731 ----------------
 732
 733 .. tabs::
 734
 735    .. group-tab:: C++
 736
 737       Please refer to :ref:`the relevant documentation <logging_prog>`.
 738
 739    .. group-tab:: Python
 740
 741        .. autofunction:: simgrid.this_actor.debug
 742        .. autofunction:: simgrid.this_actor.info
 743        .. autofunction:: simgrid.this_actor.warning
 744        .. autofunction:: simgrid.this_actor.error
 745
 746 Sleeping
 747 --------
 748
 749 .. tabs::
 750
 751    .. group-tab:: C++
 752
 753       .. doxygenfunction:: simgrid::s4u::this_actor::sleep_for(double duration)
 754       .. doxygenfunction:: simgrid::s4u::this_actor::sleep_for(std::chrono::duration< Rep, Period > duration)
 755       .. doxygenfunction:: simgrid::s4u::this_actor::sleep_until(const SimulationTimePoint< Duration > &wakeup_time)
 756       .. doxygenfunction:: simgrid::s4u::this_actor::sleep_until(double wakeup_time)
 757
 758    .. group-tab:: Python
 759
 760       .. autofunction:: simgrid.this_actor.sleep_for
 761       .. autofunction:: simgrid.this_actor.sleep_until
 762
 763    .. group-tab:: C
 764
 765       .. doxygenfunction:: sg_actor_sleep_for(double duration)
 766
 767 Simulating executions
 768 ---------------------
 769
 770 Simulate the execution of some code on this actor. You can either simulate
 771 parallel or sequential code and you can either block upon the termination of
 772 the execution, or start an asynchronous activity.
 773
 774 .. tabs::
 775
 776    .. group-tab:: C++
 777
 778       .. doxygenfunction:: simgrid::s4u::this_actor::exec_async
 779       .. doxygenfunction:: simgrid::s4u::this_actor::exec_init(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts)
 780       .. doxygenfunction:: simgrid::s4u::this_actor::exec_init(double flops_amounts)
 781       .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop)
 782       .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop, double priority)
 783       .. doxygenfunction:: simgrid::s4u::this_actor::parallel_execute(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts)
 784       .. doxygenfunction:: simgrid::s4u::this_actor::thread_execute
 785
 786    .. group-tab:: Python
 787
 788       .. autofunction:: simgrid.this_actor.exec_async
 789       .. autofunction:: simgrid.this_actor.exec_init
 790       .. autofunction:: simgrid.this_actor.execute
 791
 792    .. group-tab:: C
 793
 794       .. doxygenfunction:: sg_actor_execute(double flops)
 795       .. doxygenfunction:: sg_actor_execute_with_priority(double flops, double priority)
 796       .. doxygenfunction:: sg_actor_exec_init(double computation_amount)
 797       .. doxygenfunction:: sg_actor_exec_async(double computation_amount)
 798       .. doxygenfunction:: sg_actor_parallel_exec_init(int host_nb, const sg_host_t* host_list, double* flops_amount, double* bytes_amount);
 799
 800 Exiting
 801 -------
 802
 803 .. tabs::
 804
 805    .. group-tab:: C++
 806
 807       .. doxygenfunction:: simgrid::s4u::this_actor::exit()
 808       .. doxygenfunction:: simgrid::s4u::this_actor::on_exit(const std::function< void(bool)> &fun)
 809
 810    .. group-tab:: Python
 811
 812       .. autofunction:: simgrid.this_actor.exit
 813       .. autofunction:: simgrid.this_actor.on_exit
 814
 815    .. group-tab:: c
 816
 817       See also :cpp:func:`sg_actor_on_exit`.
 818
 819       .. doxygenfunction:: sg_actor_exit
 820
 821 .. _API_s4u_Engine:
 822
 823 ====================
 824 ⁣  Simulation Engine
 825 ====================
 826
 827 .. tabs::
 828
 829    .. group-tab:: C++
 830
 831       .. doxygenclass:: simgrid::s4u::Engine
 832
 833    .. group-tab:: Python
 834
 835       .. autoclass:: simgrid.Engine
 836
 837 Engin initialization
 838 --------------------
 839
 840 .. tabs::
 841
 842    .. group-tab:: C++
 843
 844       .. doxygenfunction:: simgrid::s4u::Engine::Engine(int *argc, char **argv)
 845       .. doxygenfunction:: simgrid::s4u::Engine::is_initialized()
 846       .. doxygenfunction:: simgrid::s4u::Engine::shutdown()
 847       .. doxygenfunction:: simgrid::s4u::Engine::get_instance()
 848
 849    .. group-tab:: Python
 850
 851        .. automethod:: simgrid.Engine.__init__
 852        .. autoattribute:: simgrid.Engine.instance
 853
 854    .. group-tab:: C
 855
 856       .. doxygenfunction:: simgrid_init
 857
 858 Simulation setup
 859 ----------------
 860
 861 .. tabs::
 862
 863    .. group-tab:: C++
 864
 865       .. doxygenfunction:: simgrid::s4u::Engine::set_config(const std::string &str)
 866       .. doxygenfunction:: simgrid::s4u::Engine::set_config(const std::string &name, bool value)
 867       .. doxygenfunction:: simgrid::s4u::Engine::set_config(const std::string &name, double value)
 868       .. doxygenfunction:: simgrid::s4u::Engine::set_config(const std::string &name, int value)
 869       .. doxygenfunction:: simgrid::s4u::Engine::set_config(const std::string &name, const std::string &value)
 870
 871       .. doxygenfunction:: simgrid::s4u::Engine::load_deployment
 872       .. doxygenfunction:: simgrid::s4u::Engine::load_platform
 873       .. doxygenfunction:: simgrid::s4u::Engine::flatify_platform
 874       .. doxygenfunction:: simgrid::s4u::Engine::register_actor(const std::string &name)
 875       .. doxygenfunction:: simgrid::s4u::Engine::register_actor(const std::string &name, F code)
 876       .. doxygenfunction:: simgrid::s4u::Engine::register_default(const std::function< void(int, char **)> &code)
 877       .. doxygenfunction:: simgrid::s4u::Engine::register_default(const kernel::actor::ActorCodeFactory &factory)
 878
 879       .. doxygenfunction:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(int, char **)> &code)
 880       .. doxygenfunction:: simgrid::s4u::Engine::register_function(const std::string &name, const std::function< void(std::vector< std::string >)> &code)
 881       .. doxygenfunction:: simgrid::s4u::Engine::register_function(const std::string &name, const kernel::actor::ActorCodeFactory &factory)
 882
 883    .. group-tab:: Python
 884
 885        .. automethod:: simgrid.Engine.load_deployment
 886        .. automethod:: simgrid.Engine.load_platform
 887        .. automethod:: simgrid.Engine.register_actor
 888
 889    .. group-tab:: C
 890
 891       .. doxygenfunction:: simgrid_load_deployment
 892       .. doxygenfunction:: simgrid_load_platform
 893       .. doxygenfunction:: simgrid_register_default
 894       .. doxygenfunction:: simgrid_register_function
 895
 896
 897 Run the simulation
 898 ------------------
 899
 900 .. tabs::
 901
 902    .. group-tab:: C++
 903
 904       .. doxygenfunction:: simgrid::s4u::Engine::get_clock()
 905       .. doxygenfunction:: simgrid::s4u::Engine::run
 906       .. doxygenfunction:: simgrid::s4u::Engine::run_until
 907
 908    .. group-tab:: Python
 909
 910       .. autoattribute:: simgrid.Engine.clock
 911       .. automethod:: simgrid.Engine.run
 912       .. automethod:: simgrid.Engine.run_until
 913
 914    .. group-tab:: C
 915
 916       .. doxygenfunction:: simgrid_get_clock
 917       .. doxygenfunction:: simgrid_run
 918       .. doxygenfunction:: simgrid_run_until
 919
 920 Retrieving actors
 921 -----------------
 922
 923 .. tabs::
 924
 925    .. group-tab:: C++
 926
 927       .. doxygenfunction:: simgrid::s4u::Engine::get_actor_count
 928       .. doxygenfunction:: simgrid::s4u::Engine::get_all_actors
 929       .. doxygenfunction:: simgrid::s4u::Engine::get_filtered_actors
 930
 931    .. group-tab:: C
 932
 933       .. doxygenfunction:: sg_actor_count()
 934
 935 Retrieving hosts
 936 ----------------
 937
 938 .. tabs::
 939
 940    .. group-tab:: C++
 941
 942       .. doxygenfunction:: simgrid::s4u::Engine::get_all_hosts
 943       .. doxygenfunction:: simgrid::s4u::Engine::get_host_count
 944       .. doxygenfunction:: simgrid::s4u::Engine::get_filtered_hosts
 945       .. doxygenfunction:: simgrid::s4u::Engine::host_by_name
 946       .. doxygenfunction:: simgrid::s4u::Engine::host_by_name_or_null
 947
 948    .. group-tab:: Python
 949
 950       .. autoattribute:: simgrid.Engine.all_hosts
 951       .. automethod:: simgrid.Engine.host_by_name
 952
 953    .. group-tab:: C
 954
 955       See also :cpp:func:`sg_host_list` and :cpp:func:`sg_host_count`.
 956
 957 Retrieving links
 958 ----------------
 959
 960 .. tabs::
 961
 962    .. group-tab:: C++
 963
 964       .. doxygenfunction:: simgrid::s4u::Engine::get_all_links
 965       .. doxygenfunction:: simgrid::s4u::Engine::get_link_count
 966       .. doxygenfunction:: simgrid::s4u::Engine::get_filtered_links
 967       .. doxygenfunction:: simgrid::s4u::Engine::link_by_name
 968       .. doxygenfunction:: simgrid::s4u::Engine::link_by_name_or_null
 969
 970    .. group-tab:: Python
 971
 972       .. autoattribute:: simgrid.Engine.all_links
 973
 974 Interacting with the routing
 975 ----------------------------
 976
 977 .. tabs::
 978
 979    .. group-tab:: C++
 980
 981       .. doxygenfunction:: simgrid::s4u::Engine::get_all_netpoints
 982       .. doxygenfunction:: simgrid::s4u::Engine::get_filtered_netzones
 983       .. doxygenfunction:: simgrid::s4u::Engine::get_netzone_root
 984       .. doxygenfunction:: simgrid::s4u::Engine::netpoint_by_name_or_null
 985       .. doxygenfunction:: simgrid::s4u::Engine::netzone_by_name_or_null
 986
 987    .. group-tab:: Python
 988
 989       .. autoattribute:: simgrid.Engine.all_netpoints
 990       .. autoattribute:: simgrid.Engine.netzone_root
 991       .. automethod:: simgrid.Engine.netpoint_by_name
 992       .. automethod:: simgrid.Engine.netzone_by_name
 993
 994 Signals
 995 -------
 996
 997 .. tabs::
 998
 999    .. group-tab:: C++
1000
1001       .. doxygenfunction:: simgrid::s4u::Engine::on_deadlock_cb
1002       .. doxygenfunction:: simgrid::s4u::Engine::on_platform_created_cb
1003       .. doxygenfunction:: simgrid::s4u::Engine::on_platform_creation_cb
1004       .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_start_cb
1005       .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_end_cb
1006       .. doxygenfunction:: simgrid::s4u::Engine::on_time_advance_cb
1007
1008 .. _API_s4u_Mailbox:
1009
1010 ================
1011 ⁣  class Mailbox
1012 ================
1013
1014 .. tabs::
1015
1016    .. group-tab:: C++
1017
1018       .. doxygenclass:: simgrid::s4u::Mailbox
1019
1020    .. group-tab:: Python
1021
1022       .. autoclass:: simgrid.Mailbox
1023
1024 Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
1025
1026 Basic management
1027 ----------------
1028
1029 .. tabs::
1030
1031    .. group-tab:: C++
1032
1033       .. code-block:: C++
1034
1035          #include <simgrid/s4u/Mailbox.hpp>
1036
1037       Note that there is no MailboxPtr type and that you cannot use the RAII
1038       idiom on mailboxes because they are internal objects to the simulation
1039       engine. Once created, there is no way to destroy a mailbox before the end
1040       of the simulation.
1041
1042       .. doxygenfunction:: simgrid::s4u::Mailbox::by_name(const std::string &name)
1043
1044    .. group-tab:: Python
1045
1046       .. code-block:: C++
1047
1048          #include <simgrid/mailbox.h>
1049
1050       .. automethod:: simgrid.Mailbox.by_name
1051
1052    .. group-tab:: C
1053
1054       .. code-block:: C
1055
1056          #include <simgrid/s4u/mailbox.h>
1057
1058       .. doxygentypedef:: sg_mailbox_t
1059       .. doxygentypedef:: const_sg_mailbox_t
1060
1061       .. doxygenfunction:: sg_mailbox_by_name(const char *alias)
1062
1063 Querying info
1064 -------------
1065
1066 .. tabs::
1067
1068    .. group-tab:: C++
1069
1070       .. doxygenfunction:: simgrid::s4u::Mailbox::get_cname
1071       .. doxygenfunction:: simgrid::s4u::Mailbox::get_name
1072
1073    .. group-tab:: Python
1074
1075       .. autoattribute:: simgrid.Mailbox.name
1076
1077 Sending data
1078 ------------
1079
1080 .. tabs::
1081
1082    .. group-tab:: C++
1083
1084       .. doxygenfunction:: simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes)
1085       .. doxygenfunction:: simgrid::s4u::Mailbox::put(void *payload, uint64_t simulated_size_in_bytes, double timeout)
1086       .. doxygenfunction:: simgrid::s4u::Mailbox::put_async(void *data, uint64_t simulated_size_in_bytes)
1087       .. doxygenfunction:: simgrid::s4u::Mailbox::put_init()
1088       .. doxygenfunction:: simgrid::s4u::Mailbox::put_init(void *data, uint64_t simulated_size_in_bytes)
1089
1090    .. group-tab:: Python
1091
1092       .. automethod:: simgrid.Mailbox.put
1093       .. automethod:: simgrid.Mailbox.put_async
1094       .. automethod:: simgrid.Mailbox.put_init
1095
1096    .. group-tab:: C
1097
1098       .. doxygenfunction:: sg_mailbox_put(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
1099       .. doxygenfunction:: sg_mailbox_put_init(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
1100       .. doxygenfunction:: sg_mailbox_put_async(sg_mailbox_t mailbox, void *payload, long simulated_size_in_bytes)
1101
1102
1103 Receiving data
1104 --------------
1105
1106 .. tabs::
1107
1108    .. group-tab:: C++
1109
1110       .. doxygenfunction:: simgrid::s4u::Mailbox::empty
1111       .. doxygenfunction:: simgrid::s4u::Mailbox::front
1112       .. doxygenfunction:: simgrid::s4u::Mailbox::get()
1113       .. doxygenfunction:: simgrid::s4u::Mailbox::get(double timeout)
1114       .. doxygenfunction:: simgrid::s4u::Mailbox::get_async(T **data)
1115       .. doxygenfunction:: simgrid::s4u::Mailbox::get_init()
1116       .. doxygenfunction:: simgrid::s4u::Mailbox::iprobe(int type, const std::function<bool(void *, void *, kernel::activity::CommImpl *)>& match_fun, void *data)
1117       .. doxygenfunction:: simgrid::s4u::Mailbox::listen
1118       .. doxygenfunction:: simgrid::s4u::Mailbox::ready
1119
1120    .. group-tab:: Python
1121
1122        .. automethod:: simgrid.Mailbox.get
1123        .. automethod:: simgrid.Mailbox.get_async
1124        .. autoattribute:: simgrid.Mailbox.ready
1125
1126    .. group-tab:: C
1127
1128       .. doxygenfunction:: sg_mailbox_get(sg_mailbox_t mailbox)
1129       .. doxygenfunction:: sg_mailbox_get_async(sg_mailbox_t mailbox, void **data)
1130       .. doxygenfunction:: sg_mailbox_get_name(const_sg_mailbox_t mailbox)
1131       .. doxygenfunction:: sg_mailbox_listen(const char *alias)
1132
1133 Receiving actor
1134 ---------------
1135
1136 See :ref:`s4u_receiving_actor`.
1137
1138 .. tabs::
1139
1140    .. group-tab:: C++
1141
1142       .. doxygenfunction:: simgrid::s4u::Mailbox::get_receiver
1143       .. doxygenfunction:: simgrid::s4u::Mailbox::set_receiver(ActorPtr actor)
1144
1145    .. group-tab:: C
1146
1147       .. doxygenfunction:: sg_mailbox_set_receiver(const char *alias)
1148
1149 .. _API_s4u_Resource:
1150
1151 =========
1152 Resources
1153 =========
1154
1155 .. _API_s4u_Disk:
1156
1157 =============
1158 ⁣  class Disk
1159 =============
1160
1161 .. tabs::
1162
1163    .. group-tab:: C++
1164
1165       .. doxygenclass:: simgrid::s4u::Disk
1166
1167    .. group-tab:: Python
1168
1169       .. autoclass:: simgrid.Disk
1170
1171    .. group-tab:: C
1172
1173       .. doxygentypedef:: sg_disk_t
1174       .. doxygentypedef:: const_sg_disk_t
1175
1176 Basic management
1177 ----------------
1178
1179 .. tabs::
1180
1181    .. group-tab:: C++
1182
1183       .. code-block:: C++
1184
1185          #include <simgrid/s4u/Disk.hpp>
1186
1187       Note that there is no DiskPtr type and that you cannot use the RAII
1188       idiom on disks because SimGrid does not allow (yet) to create nor
1189       destroy resources once the simulation is started.
1190
1191       .. doxygenfunction:: simgrid::s4u::Disk::seal()
1192
1193    .. group-tab:: Python
1194
1195       .. code:: Python
1196
1197          from simgrid import Disk
1198
1199       .. automethod:: simgrid.Disk.seal
1200
1201
1202 Querying info
1203 -------------
1204
1205 .. tabs::
1206
1207    .. group-tab:: C++
1208
1209       .. doxygenfunction:: simgrid::s4u::Disk::get_cname() const
1210       .. doxygenfunction:: simgrid::s4u::Disk::get_host() const
1211       .. doxygenfunction:: simgrid::s4u::Disk::get_name() const
1212       .. doxygenfunction:: simgrid::s4u::Disk::get_properties() const
1213       .. doxygenfunction:: simgrid::s4u::Disk::get_property(const std::string &key) const
1214       .. doxygenfunction:: simgrid::s4u::Disk::get_read_bandwidth() const
1215       .. doxygenfunction:: simgrid::s4u::Disk::get_write_bandwidth() const
1216       .. doxygenfunction:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value)
1217       .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy
1218
1219    .. group-tab:: Python
1220
1221       .. autoattribute:: simgrid.Disk.name
1222       .. automethod:: simgrid.Disk.set_sharing_policy
1223
1224 I/O operations
1225 --------------
1226
1227 .. tabs::
1228
1229    .. group-tab:: C++
1230
1231       .. doxygenfunction:: simgrid::s4u::Disk::io_init(sg_size_t size, s4u::Io::OpType type) const
1232       .. doxygenfunction:: simgrid::s4u::Disk::read(sg_size_t size) const
1233       .. doxygenfunction:: simgrid::s4u::Disk::read_async(sg_size_t size) const
1234       .. doxygenfunction:: simgrid::s4u::Disk::write(sg_size_t size) const
1235       .. doxygenfunction:: simgrid::s4u::Disk::write_async(sg_size_t size) const
1236
1237    .. group-tab:: Python
1238
1239       .. automethod:: simgrid.Disk.read
1240       .. automethod:: simgrid.Disk.read_async
1241       .. automethod:: simgrid.Disk.write
1242       .. automethod:: simgrid.Disk.write_async
1243
1244 Signals
1245 -------
1246
1247 .. tabs::
1248
1249    .. group-tab:: C++
1250
1251       .. doxygenfunction:: simgrid::s4u::Disk::on_creation_cb
1252       .. doxygenfunction:: simgrid::s4u::Disk::on_destruction_cb
1253       .. doxygenfunction:: simgrid::s4u::Disk::on_this_destruction_cb
1254       .. doxygenfunction:: simgrid::s4u::Disk::on_onoff_cb
1255       .. doxygenfunction:: simgrid::s4u::Disk::on_this_onoff_cb
1256
1257
1258 .. _API_s4u_Host:
1259
1260 =============
1261 ⁣  class Host
1262 =============
1263
1264 .. tabs::
1265
1266    .. group-tab:: C++
1267
1268       .. doxygenclass:: simgrid::s4u::Host
1269
1270    .. group-tab:: Python
1271
1272       .. autoclass:: simgrid.Host
1273
1274 Basic management
1275 ----------------
1276
1277 .. tabs::
1278
1279    .. group-tab:: C++
1280
1281       .. code-block:: C++
1282
1283          #include <simgrid/s4u/Host.hpp>
1284
1285       Note that there is no HostPtr type, and that you cannot use the RAII
1286       idiom on hosts because SimGrid does not allow (yet) to create nor
1287       destroy resources once the simulation is started.
1288
1289       .. doxygenfunction:: simgrid::s4u::Host::destroy()
1290       .. doxygenfunction:: simgrid::s4u::Host::seal()
1291
1292    .. group-tab:: Python
1293
1294       .. code:: Python
1295
1296          from simgrid import Host
1297
1298       .. automethod:: simgrid.Host.seal
1299
1300    .. group-tab:: C
1301
1302       .. code:: C
1303
1304          #include <simgrid/host.h>
1305
1306       .. doxygentypedef:: sg_host_t
1307       .. cpp:type:: const s4u_Host* const_sg_host_t
1308
1309          Pointer to a constant host object.
1310
1311 Retrieving hosts
1312 ----------------
1313
1314 .. tabs::
1315
1316    .. group-tab:: C++
1317
1318       See also :cpp:func:`simgrid::s4u::Engine::get_all_hosts`.
1319
1320       .. doxygenfunction:: simgrid::s4u::Host::by_name(const std::string &name)
1321       .. doxygenfunction:: simgrid::s4u::Host::by_name_or_null(const std::string &name)
1322       .. doxygenfunction:: simgrid::s4u::Host::current()
1323
1324    .. group-tab:: Python
1325
1326       See also :py:attr:`simgrid.Engine.all_hosts`.
1327
1328       .. automethod:: simgrid.Host.by_name
1329       .. automethod:: simgrid.Host.current
1330
1331    .. group-tab:: C
1332
1333       .. doxygenfunction:: sg_host_by_name(const char *name)
1334       .. doxygenfunction:: sg_host_count()
1335       .. doxygenfunction:: sg_host_list()
1336
1337 Modifying characteristics
1338 -------------------------
1339
1340 .. tabs::
1341
1342    .. group-tab:: C++
1343
1344       .. doxygenfunction:: simgrid::s4u::Host::set_core_count(int core_count)
1345       .. doxygenfunction:: simgrid::s4u::Host::set_coordinates(const std::string& coords)
1346       .. doxygenfunction:: simgrid::s4u::Host::set_sharing_policy
1347
1348    .. group-tab:: Python
1349
1350       .. autoattribute:: simgrid.Host.core_count
1351          :noindex:
1352       .. automethod:: simgrid.Host.set_coordinates
1353       .. automethod:: simgrid.Host.set_sharing_policy
1354
1355 Querying info
1356 -------------
1357
1358 .. tabs::
1359
1360    .. group-tab:: C++
1361
1362       .. doxygenfunction:: simgrid::s4u::Host::get_cname() const
1363       .. doxygenfunction:: simgrid::s4u::Host::get_core_count() const
1364       .. doxygenfunction:: simgrid::s4u::Host::get_name() const
1365       .. doxygenfunction:: simgrid::s4u::Host::get_available_speed() const
1366       .. doxygenfunction:: simgrid::s4u::Host::get_load() const
1367       .. doxygenfunction:: simgrid::s4u::Host::get_speed() const
1368
1369    .. group-tab:: Python
1370
1371       .. autoattribute:: simgrid.Host.name
1372       .. autoattribute:: simgrid.Host.core_count
1373       .. autoattribute:: simgrid.Host.load
1374       .. autoattribute:: simgrid.Host.speed
1375       .. autoattribute:: simgrid.Host.available_speed
1376
1377    .. group-tab:: C
1378
1379       .. doxygenfunction:: sg_host_core_count(const_sg_host_t host)
1380       .. doxygenfunction:: sg_host_get_name(const_sg_host_t host)
1381       .. doxygenfunction:: sg_host_get_load(const_sg_host_t host)
1382       .. doxygenfunction:: sg_host_get_speed(const_sg_host_t host)
1383
1384 User data and properties
1385 ------------------------
1386
1387 .. tabs::
1388
1389    .. group-tab:: C++
1390
1391       .. doxygenfunction:: simgrid::s4u::Host::get_properties() const
1392       .. doxygenfunction:: simgrid::s4u::Host::get_property(const std::string &key) const
1393       .. doxygenfunction:: simgrid::s4u::Host::set_properties(const std::unordered_map< std::string, std::string > &properties)
1394       .. doxygenfunction:: simgrid::s4u::Host::set_property(const std::string &key, const std::string &value)
1395
1396    .. group-tab:: C
1397
1398       .. doxygenfunction:: sg_host_set_property_value(sg_host_t host, const char *name, const char *value)
1399       .. doxygenfunction:: sg_host_get_properties(const_sg_host_t host)
1400       .. doxygenfunction:: sg_host_get_property_value(const_sg_host_t host, const char *name)
1401       .. doxygenfunction:: sg_host_extension_create(void(*deleter)(void *))
1402       .. doxygenfunction:: sg_host_extension_get(const_sg_host_t host, size_t rank)
1403
1404 Retrieving components
1405 ---------------------
1406
1407 .. tabs::
1408
1409    .. group-tab:: C++
1410
1411       .. doxygenfunction:: simgrid::s4u::Host::add_disk(const Disk *disk)
1412       .. doxygenfunction:: simgrid::s4u::Host::get_actor_count() const
1413       .. doxygenfunction:: simgrid::s4u::Host::get_all_actors() const
1414       .. doxygenfunction:: simgrid::s4u::Host::get_disks() const
1415       .. doxygenfunction:: simgrid::s4u::Host::remove_disk(const std::string &disk_name)
1416
1417    .. group-tab:: Python
1418
1419       .. automethod:: simgrid.Host.get_disks
1420
1421    .. group-tab:: C
1422
1423       .. doxygenfunction:: sg_host_get_actor_list(const_sg_host_t host, xbt_dynar_t whereto)
1424
1425 On/Off
1426 ------
1427
1428 .. tabs::
1429
1430    .. group-tab:: C++
1431
1432       .. doxygenfunction:: simgrid::s4u::Host::is_on() const
1433       .. doxygenfunction:: simgrid::s4u::Host::turn_off()
1434       .. doxygenfunction:: simgrid::s4u::Host::turn_on()
1435
1436    .. group-tab:: C
1437
1438       .. doxygenfunction:: sg_host_is_on(const_sg_host_t host)
1439       .. doxygenfunction:: sg_host_turn_off(sg_host_t host)
1440       .. doxygenfunction:: sg_host_turn_on(sg_host_t host)
1441
1442 .. _API_s4u_Host_dvfs:
1443
1444 DVFS
1445 ----
1446
1447 See also the :ref:`relevant examples <s4u_ex_dvfs>`.
1448
1449 .. tabs::
1450
1451    .. group-tab:: C++
1452
1453       .. doxygenfunction:: simgrid::s4u::Host::get_pstate() const
1454       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_count() const
1455       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_speed(unsigned long pstate_index) const
1456       .. doxygenfunction:: simgrid::s4u::Host::set_pstate(unsigned long pstate_index)
1457
1458    .. group-tab:: Python
1459
1460       .. autoattribute:: simgrid.Host.pstate
1461       .. autoattribute:: simgrid.Host.pstate_count
1462       .. automethod:: simgrid.Host.pstate_speed
1463
1464    .. group-tab:: C
1465
1466       .. doxygenfunction:: sg_host_get_available_speed(const_sg_host_t host)
1467       .. doxygenfunction:: sg_host_get_nb_pstates(const_sg_host_t host)
1468       .. doxygenfunction:: sg_host_get_pstate(const_sg_host_t host)
1469       .. doxygenfunction:: sg_host_get_pstate_speed(const_sg_host_t host, unsigned long pstate_index)
1470       .. doxygenfunction:: sg_host_set_pstate(sg_host_t host, unsigned long pstate)
1471
1472 Dynamic profiles
1473 ----------------
1474
1475 .. tabs::
1476
1477    .. group-tab:: C++
1478
1479       .. doxygenfunction:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p)
1480       .. doxygenfunction:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p)
1481
1482    .. group-tab:: Python
1483
1484       .. automethod:: simgrid.Host.set_speed_profile
1485       .. automethod:: simgrid.Host.set_state_profile
1486
1487 Execution
1488 ---------
1489
1490 .. tabs::
1491
1492    .. group-tab:: C++
1493
1494       .. doxygenfunction:: simgrid::s4u::Host::exec_async
1495       .. doxygenfunction:: simgrid::s4u::Host::execute(double flops) const
1496       .. doxygenfunction:: simgrid::s4u::Host::execute(double flops, double priority) const
1497
1498 Platform and routing
1499 --------------------
1500
1501 You can also start direct communications between two arbitrary hosts
1502 using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
1503
1504 .. tabs::
1505
1506    .. group-tab:: C++
1507
1508       .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() const
1509       .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const
1510       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const
1511       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::StandardLinkImpl * > &links, double *latency) const
1512       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, double read_bandwidth, double write_bandwidth)
1513       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, const std::string& read_bandwidth, const std::string& write_bandwidth)
1514
1515    .. group-tab:: Python
1516
1517       .. autoattribute:: simgrid.Host.netpoint
1518       .. automethod:: simgrid.Host.create_disk
1519
1520       .. automethod:: simgrid.Host.route_to
1521
1522    .. group-tab:: C
1523
1524       .. doxygenfunction:: sg_host_get_route(const_sg_host_t from, const_sg_host_t to, xbt_dynar_t links)
1525       .. doxygenfunction:: sg_host_get_route_bandwidth(const_sg_host_t from, const_sg_host_t to)
1526       .. doxygenfunction:: sg_host_get_route_latency(const_sg_host_t from, const_sg_host_t to)
1527       .. doxygenfunction:: sg_host_sendto(sg_host_t from, sg_host_t to, double byte_amount)
1528
1529 Signals
1530 -------
1531
1532 .. tabs::
1533
1534    .. group-tab:: C++
1535
1536       .. doxygenfunction:: simgrid::s4u::Host::on_creation_cb
1537       .. doxygenfunction:: simgrid::s4u::Host::on_destruction_cb
1538       .. doxygenfunction:: simgrid::s4u::Host::on_this_destruction_cb
1539       .. doxygenfunction:: simgrid::s4u::Host::on_speed_change_cb
1540       .. doxygenfunction:: simgrid::s4u::Host::on_this_speed_change_cb
1541       .. doxygenfunction:: simgrid::s4u::Host::on_onoff_cb
1542       .. doxygenfunction:: simgrid::s4u::Host::on_this_onoff_cb
1543       .. doxygenfunction:: simgrid::s4u::Host::on_exec_state_change_cb
1544
1545 .. _API_s4u_Link:
1546
1547 =============
1548 ⁣  class Link
1549 =============
1550
1551 .. tabs::
1552
1553    .. group-tab:: C++
1554
1555       .. doxygenclass:: simgrid::s4u::Link
1556       .. doxygenclass:: simgrid::s4u::SplitDuplexLink
1557       .. doxygenclass:: simgrid::s4u::LinkInRoute
1558
1559
1560    .. group-tab:: Python
1561
1562       .. autoclass:: simgrid.Link
1563
1564 Basic management
1565 ----------------
1566
1567 .. tabs::
1568
1569    .. group-tab:: C++
1570
1571       .. code-block:: C++
1572
1573          #include <simgrid/s4u/Link.hpp>
1574
1575       Note that there is no LinkPtr type and that you cannot use the RAII
1576       idiom on hosts because SimGrid does not allow (yet) to create nor
1577       destroy resources once the simulation is started.
1578
1579       .. doxygenfunction:: simgrid::s4u::Link::seal()
1580
1581    .. group-tab:: Python
1582
1583       .. code:: Python
1584
1585          from simgrid import Link
1586
1587       .. automethod:: simgrid.Link.seal
1588
1589    .. group-tab:: C
1590
1591       .. code:: C
1592
1593          #include <simgrid/link.h>
1594
1595       .. doxygentypedef:: sg_link_t
1596       .. cpp:type:: const s4u_Link* const_sg_link_t
1597
1598          Pointer to a constant link object.
1599
1600 Retrieving links
1601 ----------------
1602
1603 .. tabs::
1604
1605    .. group-tab:: C++
1606
1607       See also :cpp:func:`simgrid::s4u::Engine::get_all_links`.
1608
1609       .. doxygenfunction:: simgrid::s4u::Link::by_name(const std::string &name)
1610       .. doxygenfunction:: simgrid::s4u::Link::by_name_or_null(const std::string &name)
1611
1612    .. group-tab:: Python
1613
1614       See also :py:attr:`simgrid.Engine.all_links`.
1615
1616       .. automethod:: simgrid.Link.by_name
1617       .. autoattribute:: simgrid.Link.name
1618
1619    .. group-tab:: C
1620
1621       .. doxygenfunction:: sg_link_by_name(const char *name)
1622       .. doxygenfunction:: sg_link_count()
1623       .. doxygenfunction:: sg_link_list()
1624
1625 Querying info
1626 --------------
1627
1628 .. tabs::
1629
1630    .. group-tab:: C++
1631
1632       .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const
1633       .. doxygenfunction:: simgrid::s4u::Link::get_cname() const
1634       .. doxygenfunction:: simgrid::s4u::Link::get_latency() const
1635       .. doxygenfunction:: simgrid::s4u::Link::get_name() const
1636       .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const
1637       .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const
1638       .. doxygenfunction:: simgrid::s4u::Link::get_usage() const
1639       .. doxygenfunction:: simgrid::s4u::Link::is_used() const
1640
1641    .. group-tab:: Python
1642
1643       .. autoattribute:: simgrid.Link.bandwidth
1644       .. autoattribute:: simgrid.Link.latency
1645
1646    .. group-tab:: C
1647
1648       .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link)
1649       .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link)
1650       .. doxygenfunction:: sg_link_get_name(const_sg_link_t link)
1651       .. doxygenfunction:: sg_link_is_shared(const_sg_link_t link)
1652
1653 Modifying characteristics
1654 -------------------------
1655
1656 .. tabs::
1657
1658    .. group-tab:: C++
1659
1660       .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth(double value)
1661       .. doxygenfunction:: simgrid::s4u::Link::set_latency(double value)
1662       .. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value)
1663       .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
1664       .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
1665
1666    .. group-tab:: Python
1667
1668       .. automethod:: simgrid.Link.set_bandwidth
1669       .. automethod:: simgrid.Link.set_latency
1670       .. automethod:: simgrid.Link.set_concurrency_limit
1671       .. automethod:: simgrid.Link.set_sharing_policy
1672
1673    .. group-tab:: C
1674
1675       .. doxygenfunction:: sg_link_set_bandwidth(sg_link_t link, double value)
1676       .. doxygenfunction:: sg_link_set_latency(sg_link_t link, double value)
1677
1678 User data and properties
1679 ------------------------
1680
1681 .. tabs::
1682
1683    .. group-tab:: C++
1684
1685       .. doxygenfunction:: simgrid::s4u::Link::get_property(const std::string &key) const
1686       .. doxygenfunction:: simgrid::s4u::Link::set_property(const std::string &key, const std::string &value)
1687
1688    .. group-tab:: C
1689
1690       .. doxygenfunction:: sg_link_get_data(const_sg_link_t link)
1691       .. doxygenfunction:: sg_link_set_data(sg_link_t link, void *data)
1692
1693 On/Off
1694 ------
1695
1696 .. tabs::
1697
1698    .. group-tab:: C++
1699
1700       See also :cpp:func:`simgrid::s4u::Link::set_state_profile`.
1701
1702       .. doxygenfunction:: simgrid::s4u::Link::is_on() const
1703       .. doxygenfunction:: simgrid::s4u::Link::turn_off()
1704       .. doxygenfunction:: simgrid::s4u::Link::turn_on()
1705
1706    .. group-tab:: Python
1707
1708       See also :py:func:`simgrid.Link.set_state_profile`.
1709
1710       .. automethod:: simgrid.Link.is_on
1711       .. automethod:: simgrid.Link.turn_off
1712       .. automethod:: simgrid.Link.turn_on
1713
1714 Dynamic profiles
1715 ----------------
1716
1717 See :ref:`howto_churn` for more details.
1718
1719 .. tabs::
1720
1721    .. group-tab:: C++
1722
1723       .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth_profile(kernel::profile::Profile *profile)
1724       .. doxygenfunction:: simgrid::s4u::Link::set_latency_profile(kernel::profile::Profile *profile)
1725       .. doxygenfunction:: simgrid::s4u::Link::set_state_profile(kernel::profile::Profile *profile)
1726
1727    .. group-tab:: Python
1728
1729       .. automethod:: simgrid.Link.set_bandwidth_profile
1730       .. automethod:: simgrid.Link.set_latency_profile
1731       .. automethod:: simgrid.Link.set_state_profile
1732
1733 WIFI links
1734 ----------
1735
1736 .. tabs::
1737
1738    .. group-tab:: C++
1739
1740       .. doxygenfunction:: simgrid::s4u::Link::set_host_wifi_rate
1741
1742    .. group-tab:: Python
1743
1744       .. automethod:: simgrid.Link.set_host_wifi_rate
1745
1746 Signals
1747 -------
1748
1749 .. tabs::
1750
1751    .. group-tab:: C++
1752
1753       .. doxygenfunction:: simgrid::s4u::Link::on_bandwidth_change_cb
1754       .. doxygenfunction:: simgrid::s4u::Link::on_this_bandwidth_change_cb
1755       .. doxygenfunction:: simgrid::s4u::Link::on_communication_state_change_cb
1756       .. doxygenfunction:: simgrid::s4u::Link::on_creation_cb
1757       .. doxygenfunction:: simgrid::s4u::Link::on_destruction_cb
1758       .. doxygenfunction:: simgrid::s4u::Link::on_this_destruction_cb
1759       .. doxygenfunction:: simgrid::s4u::Link::on_onoff_cb
1760       .. doxygenfunction:: simgrid::s4u::Link::on_this_onoff_cb
1761
1762 .. _API_s4u_NetZone:
1763
1764 ================
1765 ⁣  class NetZone
1766 ================
1767
1768 .. tabs::
1769
1770    .. group-tab:: C++
1771
1772       .. doxygenclass:: simgrid::s4u::NetZone
1773
1774    .. group-tab:: Python
1775
1776       .. autoclass:: simgrid.NetZone
1777
1778 Basic management
1779 ----------------
1780
1781 .. tabs::
1782
1783    .. group-tab:: C++
1784
1785       .. code-block:: C++
1786
1787          #include <simgrid/s4u/NetZone.hpp>
1788
1789       Note that there is no NetZonePtr type and that you cannot use the RAII
1790       idiom on network zones because SimGrid does not allow (yet) to create nor
1791       destroy resources once the simulation is started.
1792
1793       .. doxygenfunction:: simgrid::s4u::NetZone::seal
1794
1795    .. group-tab:: Python
1796
1797       .. code:: Python
1798
1799          from simgrid import NetZone
1800
1801       .. automethod:: simgrid.NetZone.seal
1802
1803    .. group-tab:: C
1804
1805       .. code:: C
1806
1807          #include <simgrid/zone.h>
1808
1809       .. doxygentypedef:: sg_netzone_t
1810       .. cpp:type:: const s4u_NetZone* const_sg_netzone_t
1811
1812          Pointer to a constant network zone object.
1813
1814 Retrieving zones
1815 ----------------
1816
1817 .. tabs::
1818
1819    .. group-tab:: C++
1820
1821       See :cpp:func:`simgrid::s4u::Engine::get_netzone_root`,
1822       :cpp:func:`simgrid::s4u::Engine::netzone_by_name_or_null` and
1823       :cpp:func:`simgrid::s4u::Engine::get_filtered_netzones`.
1824
1825    .. group-tab:: C
1826
1827       .. doxygenfunction:: sg_zone_get_by_name(const char *name)
1828       .. doxygenfunction:: sg_zone_get_root()
1829
1830 Querying info
1831 --------------
1832
1833 .. tabs::
1834
1835    .. group-tab:: C++
1836
1837       .. doxygenfunction:: simgrid::s4u::NetZone::get_cname() const
1838       .. doxygenfunction:: simgrid::s4u::NetZone::get_name() const
1839       .. doxygenfunction:: simgrid::s4u::NetZone::get_netpoint()
1840
1841    .. group-tab:: Python
1842
1843       .. autoattribute:: simgrid.NetZone.name
1844       .. autoattribute:: simgrid.NetZone.netpoint
1845
1846    .. group-tab:: C
1847
1848       .. doxygenfunction:: sg_zone_get_name(const_sg_netzone_t zone)
1849
1850 User data and properties
1851 ------------------------
1852
1853 .. tabs::
1854
1855    .. group-tab:: C++
1856
1857       .. doxygenfunction:: simgrid::s4u::NetZone::get_properties() const
1858       .. doxygenfunction:: simgrid::s4u::NetZone::get_property(const std::string &key) const
1859       .. doxygenfunction:: simgrid::s4u::NetZone::set_property(const std::string &key, const std::string &value)
1860
1861    .. group-tab:: Python
1862
1863       .. automethod:: simgrid.NetZone.set_property
1864
1865    .. group-tab:: C
1866
1867       .. doxygenfunction:: sg_zone_get_property_value(const_sg_netzone_t as, const char *name)
1868       .. doxygenfunction:: sg_zone_set_property_value(sg_netzone_t netzone, const char *name, const char *value)
1869
1870 Retrieving components
1871 ---------------------
1872
1873 .. tabs::
1874
1875    .. group-tab:: C++
1876
1877       .. doxygenfunction:: simgrid::s4u::NetZone::get_all_hosts() const
1878       .. doxygenfunction:: simgrid::s4u::NetZone::get_host_count() const
1879
1880    .. group-tab:: C
1881
1882       .. doxygenfunction:: sg_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
1883
1884 Routing data
1885 ------------
1886
1887 .. tabs::
1888
1889    .. group-tab:: C++
1890
1891       .. doxygenfunction:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm)
1892       .. doxygenfunction:: simgrid::s4u::NetZone::add_route
1893       .. doxygenfunction:: simgrid::s4u::NetZone::add_bypass_route
1894       .. doxygenfunction:: simgrid::s4u::NetZone::get_children() const
1895       .. doxygenfunction:: simgrid::s4u::NetZone::get_parent() const
1896       .. doxygenfunction:: simgrid::s4u::NetZone::set_parent(const NetZone* parent)
1897
1898    .. group-tab:: Python
1899
1900       .. automethod:: simgrid.NetZone.add_route
1901       .. automethod:: simgrid.NetZone.set_parent
1902
1903    .. group-tab:: C
1904
1905       .. doxygenfunction:: sg_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
1906
1907 Signals
1908 -------
1909
1910 .. tabs::
1911
1912   .. group-tab:: C++
1913
1914      .. doxygenfunction:: simgrid::s4u::NetZone::on_creation_cb
1915      .. doxygenfunction:: simgrid::s4u::NetZone::on_seal_cb
1916
1917 Creating resources
1918 ------------------
1919
1920 Zones
1921 ^^^^^
1922 .. tabs::
1923
1924   .. group-tab:: C++
1925
1926      .. doxygenfunction:: simgrid::s4u::create_full_zone
1927      .. doxygenfunction:: simgrid::s4u::create_empty_zone
1928      .. doxygenfunction:: simgrid::s4u::create_star_zone
1929      .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone
1930      .. doxygenfunction:: simgrid::s4u::create_floyd_zone
1931      .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone
1932      .. doxygenfunction:: simgrid::s4u::create_wifi_zone
1933      .. doxygenfunction:: simgrid::s4u::create_torus_zone
1934      .. doxygenfunction:: simgrid::s4u::create_fatTree_zone
1935      .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone
1936
1937   .. group-tab:: Python
1938
1939      .. automethod:: simgrid.NetZone.create_full_zone
1940      .. automethod:: simgrid.NetZone.create_empty_zone
1941      .. automethod:: simgrid.NetZone.create_star_zone
1942      .. automethod:: simgrid.NetZone.create_dijkstra_zone
1943      .. automethod:: simgrid.NetZone.create_floyd_zone
1944      .. automethod:: simgrid.NetZone.create_vivaldi_zone
1945      .. automethod:: simgrid.NetZone.create_wifi_zone
1946      .. automethod:: simgrid.NetZone.create_torus_zone
1947      .. automethod:: simgrid.NetZone.create_fatTree_zone
1948      .. automethod:: simgrid.NetZone.create_dragonfly_zone
1949
1950 Hosts
1951 ^^^^^
1952
1953 .. tabs::
1954
1955   .. group-tab:: C++
1956
1957      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::vector<double>& speed_per_pstate)
1958      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, double speed)
1959      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::vector<std::string>& speed_per_pstate)
1960      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::string& speed)
1961
1962   .. group-tab:: Python
1963
1964      .. automethod:: simgrid.NetZone.create_host
1965
1966 Links
1967 ^^^^^
1968
1969 .. tabs::
1970
1971   .. group-tab:: C++
1972
1973      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<double>& bandwidths)
1974      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, double bandwidth)
1975      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<std::string>& bandwidthds)
1976      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::string& bandwidth)
1977      .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, const std::string& bandwidth)
1978      .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, double bandwidth)
1979
1980   .. group-tab:: Python
1981
1982      .. automethod:: simgrid.NetZone.create_link
1983      .. automethod:: simgrid.NetZone.create_split_duplex_link
1984
1985 Router
1986 ^^^^^^
1987
1988 .. tabs::
1989
1990   .. group-tab:: C++
1991
1992      .. doxygenfunction:: simgrid::s4u::NetZone::create_router(const std::string& name)
1993
1994   .. group-tab:: Python
1995
1996      .. automethod:: simgrid.NetZone.create_router
1997
1998 .. _API_s4u_VirtualMachine:
1999
2000 =======================
2001 ⁣  class VirtualMachine
2002 =======================
2003
2004
2005 .. doxygenclass:: simgrid::s4u::VirtualMachine
2006
2007 Basic management
2008 ----------------
2009 .. tabs::
2010
2011    .. group-tab:: C++
2012
2013       .. code-block:: C++
2014
2015          #include <simgrid/s4u/VirtualMachine.hpp>
2016
2017       Note that there is no VirtualMachinePtr type, and that you cannot use the RAII
2018       idiom on virtual machines. There is no good reason for that and should change in the future.
2019
2020    .. group-tab:: C
2021
2022       .. code:: C
2023
2024          #include <simgrid/vm.h>
2025
2026       .. doxygentypedef:: sg_vm_t
2027       .. cpp:type:: const s4u_VirtualMachine* const_sg_vm_t
2028
2029          Pointer to a constant virtual machine object.
2030
2031 Creating VMs
2032 ------------
2033
2034 .. tabs::
2035
2036    .. group-tab:: C++
2037
2038       .. doxygenfunction:: simgrid::s4u::Host::create_vm(const std::string &name, int core_amount)
2039       .. doxygenfunction:: simgrid::s4u::Host::create_vm(const std::string &name, int core_amount, size_t ramsize)
2040       .. doxygenfunction:: simgrid::s4u::VirtualMachine::destroy
2041
2042    .. group-tab:: C
2043
2044       .. doxygenfunction:: sg_vm_create_core
2045       .. doxygenfunction:: sg_vm_create_multicore
2046       .. doxygenfunction:: sg_vm_destroy
2047
2048 Querying info
2049 --------------
2050
2051 .. tabs::
2052
2053    .. group-tab:: C++
2054
2055       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_pm() const
2056       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_ramsize() const
2057       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_state() const
2058
2059       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_bound(double bound)
2060       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_pm(Host *pm)
2061       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_ramsize(size_t ramsize)
2062
2063    .. group-tab:: C
2064
2065       .. doxygenfunction:: sg_vm_get_ramsize(const_sg_vm_t vm)
2066       .. doxygenfunction:: sg_vm_set_bound(sg_vm_t vm, double bound)
2067       .. doxygenfunction:: sg_vm_set_ramsize(sg_vm_t vm, size_t size)
2068
2069       .. doxygenfunction:: sg_vm_get_name
2070       .. doxygenfunction:: sg_vm_get_pm
2071       .. doxygenfunction:: sg_vm_is_created
2072       .. doxygenfunction:: sg_vm_is_running
2073       .. doxygenfunction:: sg_vm_is_suspended
2074
2075 Life cycle
2076 ----------
2077
2078 .. tabs::
2079
2080    .. group-tab:: C++
2081
2082       .. doxygenfunction:: simgrid::s4u::VirtualMachine::resume()
2083       .. doxygenfunction:: simgrid::s4u::VirtualMachine::shutdown()
2084       .. doxygenfunction:: simgrid::s4u::VirtualMachine::start()
2085       .. doxygenfunction:: simgrid::s4u::VirtualMachine::suspend()
2086
2087    .. group-tab:: C
2088
2089       .. doxygenfunction:: sg_vm_start
2090       .. doxygenfunction:: sg_vm_suspend
2091       .. doxygenfunction:: sg_vm_resume
2092       .. doxygenfunction:: sg_vm_shutdown
2093
2094 Signals
2095 -------
2096
2097 .. tabs::
2098
2099    .. group-tab:: C++
2100
2101       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_creation_cb
2102       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_destruction_cb
2103       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_destruction_cb
2104       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_end_cb
2105       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_migration_end_cb
2106       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_start_cb
2107       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_migration_start_cb
2108       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_resume_cb
2109       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_resume_cb
2110       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_shutdown_cb
2111       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_shutdown_cb
2112       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_start_cb
2113       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_start_cb
2114       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_started_cb
2115       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_started_cb
2116       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_suspend_cb
2117       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_suspend_cb
2118
2119 .. _API_s4u_Activity:
2120
2121 ==========
2122 Activities
2123 ==========
2124
2125 ==============
2126 class Activity
2127 ==============
2128
2129 .. doxygenclass:: simgrid::s4u::Activity
2130
2131 **Known subclasses:**
2132 :ref:`Communications <API_s4u_Comm>` (started on Mailboxes and consuming links),
2133 :ref:`Executions <API_s4u_Exec>` (started on Host and consuming CPU resources)
2134 :ref:`I/O <API_s4u_Io>` (started on and consuming disks).
2135 See also the :ref:`section on activities <s4u_Activities>` above.
2136
2137 Basic management
2138 ----------------
2139
2140 .. tabs::
2141
2142    .. group-tab:: C++
2143
2144       .. code-block:: C++
2145
2146          #include <simgrid/s4u/Activity.hpp>
2147
2148       .. doxygentypedef:: ActivityPtr
2149
2150 Querying info
2151 -------------
2152
2153 .. tabs::
2154
2155    .. group-tab:: C++
2156
2157       .. doxygenfunction:: simgrid::s4u::Activity::get_cname() const
2158       .. doxygenfunction:: simgrid::s4u::Activity::get_name() const
2159       .. doxygenfunction:: simgrid::s4u::Activity::get_remaining() const
2160       .. doxygenfunction:: simgrid::s4u::Activity::get_state() const
2161       .. doxygenfunction:: simgrid::s4u::Activity::set_remaining(double remains)
2162       .. doxygenfunction:: simgrid::s4u::Activity::set_state(Activity::State state)
2163
2164
2165 Activities life cycle
2166 ---------------------
2167
2168 .. tabs::
2169
2170    .. group-tab:: C++
2171
2172       .. doxygenfunction:: simgrid::s4u::Activity::start
2173       .. doxygenfunction:: simgrid::s4u::Activity::cancel
2174       .. doxygenfunction:: simgrid::s4u::Activity::test
2175       .. doxygenfunction:: simgrid::s4u::Activity::wait
2176       .. doxygenfunction:: simgrid::s4u::Activity::wait_for
2177       .. doxygenfunction:: simgrid::s4u::Activity::wait_until(double time_limit)
2178       .. doxygenfunction:: simgrid::s4u::Activity::vetoable_start()
2179
2180 Suspending and resuming an activity
2181 -----------------------------------
2182
2183 .. tabs::
2184
2185    .. group-tab:: C++
2186
2187       .. doxygenfunction:: simgrid::s4u::Activity::suspend
2188       .. doxygenfunction:: simgrid::s4u::Activity::resume
2189       .. doxygenfunction:: simgrid::s4u::Activity::is_suspended
2190
2191 .. _API_s4u_Comm:
2192
2193 =============
2194 ⁣  class Comm
2195 =============
2196
2197 .. tabs::
2198
2199    .. group-tab:: C++
2200
2201       .. doxygenclass:: simgrid::s4u::Comm
2202
2203    .. group-tab:: Python
2204
2205       .. autoclass:: simgrid.Comm
2206
2207 Basic management
2208 ----------------
2209
2210 .. tabs::
2211
2212    .. group-tab:: C++
2213
2214       .. code-block:: C++
2215
2216          #include <simgrid/s4u/Comm.hpp>
2217
2218       .. doxygentypedef:: CommPtr
2219
2220    .. group-tab:: Python
2221
2222       .. code:: Python
2223
2224          from simgrid import Comm
2225
2226    .. group-tab:: c
2227
2228       .. code:: c
2229
2230          #include <simgrid/comm.h>
2231
2232       .. doxygentypedef:: sg_comm_t
2233
2234 Querying info
2235 -------------
2236
2237 .. tabs::
2238
2239    .. group-tab:: C++
2240
2241       .. doxygenfunction:: simgrid::s4u::Comm::get_dst_data_size() const
2242       .. doxygenfunction:: simgrid::s4u::Comm::get_mailbox() const
2243       .. doxygenfunction:: simgrid::s4u::Comm::get_sender() const
2244       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff)
2245       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size)
2246       .. doxygenfunction:: simgrid::s4u::Comm::detach()
2247       .. doxygenfunction:: simgrid::s4u::Comm::detach(const std::function<void(void*)>& clean_function)
2248       .. doxygenfunction:: simgrid::s4u::Comm::set_payload_size(uint64_t bytes)
2249       .. doxygenfunction:: simgrid::s4u::Comm::set_rate(double rate)
2250       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff)
2251       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size)
2252       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data_size(size_t size)
2253
2254    .. group-tab:: Python
2255
2256       .. autoattribute:: simgrid.Comm.dst_data_size
2257       .. autoattribute:: simgrid.Comm.mailbox
2258       .. autoattribute:: simgrid.Comm.sender
2259       .. autoattribute:: simgrid.Comm.state_str
2260       .. automethod:: simgrid.Comm.detach
2261       .. automethod:: simgrid.Comm.set_payload_size
2262       .. automethod:: simgrid.Comm.set_rate
2263
2264 Direct host-to-host communication
2265 ---------------------------------
2266
2267 Most communications are created using :ref:`s4u_mailbox`, but you can
2268 also start direct communications as shown below. See also the
2269 :ref:`relevant examples <s4u_ex_comm_host2host>`.
2270
2271 .. tabs::
2272
2273    .. group-tab:: C++
2274
2275       .. doxygenfunction:: simgrid::s4u::Comm::sendto
2276       .. doxygenfunction:: simgrid::s4u::Comm::sendto_init()
2277       .. doxygenfunction:: simgrid::s4u::Comm::sendto_init(Host *from, Host *to)
2278       .. doxygenfunction:: simgrid::s4u::Comm::sendto_async
2279
2280    .. group-tab:: Python
2281
2282       .. automethod:: simgrid.Comm.sendto
2283       .. automethod:: simgrid.Comm.sendto_init
2284       .. automethod:: simgrid.Comm.sendto_async
2285
2286 Life cycle
2287 ----------
2288
2289 .. tabs::
2290
2291    .. group-tab:: C++
2292
2293       .. doxygenfunction:: simgrid::s4u::Comm::cancel
2294       .. doxygenfunction:: simgrid::s4u::Comm::start
2295       .. doxygenfunction:: simgrid::s4u::Comm::test
2296       .. doxygenfunction:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr >& comms)
2297       .. doxygenfunction:: simgrid::s4u::Comm::wait
2298       .. doxygenfunction:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr >& comms)
2299       .. doxygenfunction:: simgrid::s4u::Comm::wait_all_for(const std::vector< CommPtr >& comms, double timeout)
2300       .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr >& comms)
2301       .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr >& comms, double timeout)
2302       .. doxygenfunction:: simgrid::s4u::Comm::wait_for
2303       .. doxygenfunction:: simgrid::s4u::Comm::wait_until
2304
2305    .. group-tab:: Python
2306
2307       .. automethod:: simgrid.Comm.cancel
2308       .. automethod:: simgrid.Comm.start
2309       .. automethod:: simgrid.Comm.test
2310       .. automethod:: simgrid.Comm.test_any
2311       .. automethod:: simgrid.Comm.wait
2312       .. automethod:: simgrid.Comm.wait_for
2313       .. automethod:: simgrid.Comm.wait_all
2314       .. automethod:: simgrid.Comm.wait_all_for
2315       .. automethod:: simgrid.Comm.wait_any
2316       .. automethod:: simgrid.Comm.wait_any_for
2317       .. automethod:: simgrid.Comm.wait_until
2318
2319    .. group-tab:: C
2320
2321       .. doxygenfunction:: sg_comm_test
2322       .. doxygenfunction:: sg_comm_wait
2323       .. doxygenfunction:: sg_comm_wait_all
2324       .. doxygenfunction:: sg_comm_wait_any
2325
2326 Suspending and resuming a communication
2327 ---------------------------------------
2328
2329 .. tabs::
2330
2331    .. group-tab:: C++
2332
2333       .. doxygenfunction:: simgrid::s4u::Comm::suspend
2334       .. doxygenfunction:: simgrid::s4u::Comm::resume
2335       .. doxygenfunction:: simgrid::s4u::Comm::is_suspended
2336
2337    .. group-tab:: Python
2338
2339       .. automethod:: simgrid.Comm.suspend
2340       .. automethod:: simgrid.Comm.resume
2341       .. autoattribute:: simgrid.Comm.is_suspended
2342
2343 Signals
2344 -------
2345
2346 .. tabs::
2347
2348    .. group-tab:: C++
2349
2350       .. doxygenfunction:: simgrid::s4u::Comm::on_start_cb
2351       .. doxygenfunction:: simgrid::s4u::Comm::on_this_start_cb
2352       .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb
2353       .. doxygenfunction:: simgrid::s4u::Comm::on_this_completion_cb
2354       .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb
2355       .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb
2356       .. doxygenfunction:: simgrid::s4u::Comm::on_suspended_cb
2357       .. doxygenfunction:: simgrid::s4u::Comm::on_resumed_cb
2358       .. doxygenfunction:: simgrid::s4u::Comm::on_veto_cb
2359
2360 .. _API_s4u_Exec:
2361
2362 =============
2363 ⁣  class Exec
2364 =============
2365
2366 .. tabs::
2367
2368    .. group-tab:: C++
2369
2370       .. doxygenclass:: simgrid::s4u::Exec
2371
2372    .. group-tab:: Python
2373
2374       .. autoclass:: simgrid.Exec
2375
2376 Basic management
2377 ----------------
2378
2379 .. tabs::
2380
2381    .. group-tab:: C++
2382
2383       .. code-block:: C++
2384
2385          #include <simgrid/s4u/Exec.hpp>
2386
2387       .. doxygentypedef:: ExecPtr
2388
2389    .. group-tab:: Python
2390
2391       .. code:: Python
2392
2393          from simgrid import Exec
2394
2395    .. group-tab:: C
2396
2397       .. code-block:: C
2398
2399          #include <simgrid/exec.h>
2400
2401       .. doxygentypedef:: sg_exec_t
2402       .. doxygentypedef:: const_sg_exec_t
2403
2404 Querying info
2405 -------------
2406
2407 .. tabs::
2408
2409    .. group-tab:: C++
2410
2411       .. doxygenfunction:: simgrid::s4u::Exec::get_cost() const
2412       .. doxygenfunction:: simgrid::s4u::Exec::get_finish_time() const
2413       .. doxygenfunction:: simgrid::s4u::Exec::get_host() const
2414       .. doxygenfunction:: simgrid::s4u::Exec::get_host_number() const
2415       .. doxygenfunction:: simgrid::s4u::Exec::get_remaining
2416       .. doxygenfunction:: simgrid::s4u::Exec::get_remaining_ratio
2417       .. doxygenfunction:: simgrid::s4u::Exec::get_start_time() const
2418       .. doxygenfunction:: simgrid::s4u::Exec::set_bound(double bound)
2419       .. doxygenfunction:: simgrid::s4u::Exec::set_host
2420       .. doxygenfunction:: simgrid::s4u::Exec::set_priority(double priority)
2421
2422    .. group-tab:: Python
2423
2424       .. autoattribute:: simgrid.Exec.host
2425       .. autoattribute:: simgrid.Exec.remaining
2426       .. autoattribute:: simgrid.Exec.remaining_ratio
2427
2428    .. group-tab:: C
2429
2430       .. doxygenfunction:: sg_exec_set_bound(sg_exec_t exec, double bound)
2431       .. doxygenfunction:: sg_exec_get_name(const_sg_exec_t exec)
2432       .. doxygenfunction:: sg_exec_set_name(sg_exec_t exec, const char* name)
2433       .. doxygenfunction:: sg_exec_set_host(sg_exec_t exec, sg_host_t new_host)
2434       .. doxygenfunction:: sg_exec_get_remaining(const_sg_exec_t exec)
2435       .. doxygenfunction:: sg_exec_get_remaining_ratio(const_sg_exec_t exec)
2436
2437 Life cycle
2438 ----------
2439
2440 .. tabs::
2441
2442    .. group-tab:: C++
2443
2444       .. doxygenfunction:: simgrid::s4u::Exec::cancel
2445       .. doxygenfunction:: simgrid::s4u::Exec::start
2446       .. doxygenfunction:: simgrid::s4u::Exec::test
2447       .. doxygenfunction:: simgrid::s4u::Exec::wait
2448       .. doxygenfunction:: simgrid::s4u::Exec::wait_any(const std::vector< ExecPtr >& execs)
2449       .. doxygenfunction:: simgrid::s4u::Exec::wait_any_for(const std::vector< ExecPtr >& execs, double timeout)
2450       .. doxygenfunction:: simgrid::s4u::Exec::wait_for
2451
2452    .. group-tab:: Python
2453
2454        .. automethod:: simgrid.Exec.cancel
2455        .. automethod:: simgrid.Exec.start
2456        .. automethod:: simgrid.Exec.test
2457        .. automethod:: simgrid.Exec.wait
2458
2459    .. group-tab:: C
2460
2461        .. doxygenfunction:: sg_exec_start(sg_exec_t exec)
2462        .. doxygenfunction:: sg_exec_cancel(sg_exec_t exec);
2463        .. doxygenfunction:: sg_exec_test(sg_exec_t exec);
2464        .. doxygenfunction:: sg_exec_wait(sg_exec_t exec);
2465        .. doxygenfunction:: sg_exec_wait_for(sg_exec_t exec, double timeout);
2466        .. doxygenfunction:: sg_exec_wait_any_for(sg_exec_t* execs, size_t count, double timeout);
2467        .. doxygenfunction:: sg_exec_wait_any(sg_exec_t* execs, size_t count);
2468
2469 Suspending and resuming an execution
2470 ------------------------------------
2471
2472 .. tabs::
2473
2474    .. group-tab:: C++
2475
2476       .. doxygenfunction:: simgrid::s4u::Exec::suspend
2477       .. doxygenfunction:: simgrid::s4u::Exec::resume
2478       .. doxygenfunction:: simgrid::s4u::Exec::is_suspended
2479
2480    .. group-tab:: Python
2481
2482       .. automethod:: simgrid.Exec.suspend
2483       .. automethod:: simgrid.Exec.resume
2484       .. autoattribute:: simgrid.Exec.is_suspended
2485
2486 Signals
2487 -------
2488
2489 .. tabs::
2490
2491    .. group-tab:: C++
2492
2493       .. doxygenfunction:: simgrid::s4u::Exec::on_start_cb
2494       .. doxygenfunction:: simgrid::s4u::Exec::on_this_start_cb
2495       .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb
2496       .. doxygenfunction:: simgrid::s4u::Exec::on_this_completion_cb
2497
2498       .. doxygenfunction:: simgrid::s4u::Exec::on_suspended_cb
2499       .. doxygenfunction:: simgrid::s4u::Exec::on_resumed_cb
2500       .. doxygenfunction:: simgrid::s4u::Exec::on_veto_cb
2501
2502 .. _API_s4u_Io:
2503
2504 ===========
2505 ⁣  class Io
2506 ===========
2507
2508 .. tabs::
2509
2510    .. group-tab:: C++
2511
2512       .. doxygenclass:: simgrid::s4u::Io
2513
2514    .. group-tab:: Python
2515
2516       .. autoclass:: simgrid.Io
2517
2518 Basic management
2519 ----------------
2520
2521 .. tabs::
2522
2523    .. group-tab:: C++
2524
2525       .. code-block:: C++
2526
2527          #include <simgrid/s4u/Io.hpp>
2528
2529       .. doxygentypedef:: IoPtr
2530
2531 Querying info
2532 -------------
2533
2534 .. tabs::
2535
2536    .. group-tab:: C++
2537
2538       .. doxygenfunction:: simgrid::s4u::Io::get_performed_ioops() const
2539       .. doxygenfunction:: simgrid::s4u::Io::get_remaining
2540
2541 Life cycle
2542 ----------
2543
2544 .. tabs::
2545
2546    .. group-tab:: C++
2547
2548       .. doxygenfunction:: simgrid::s4u::Io::cancel
2549       .. doxygenfunction:: simgrid::s4u::Io::start
2550       .. doxygenfunction:: simgrid::s4u::Io::test
2551       .. doxygenfunction:: simgrid::s4u::Io::wait
2552       .. doxygenfunction:: simgrid::s4u::Io::wait_for
2553       .. doxygenfunction:: simgrid::s4u::Io::wait_any(const std::vector<IoPtr> &ios)
2554       .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector<IoPtr> &ios, double timeout)
2555
2556    .. group-tab:: Python
2557
2558       .. automethod:: simgrid.Io.test
2559       .. automethod:: simgrid.Io.wait
2560       .. automethod:: simgrid.Io.wait_any_for
2561       .. automethod:: simgrid.Io.wait_any
2562
2563 Signals
2564 -------
2565
2566 .. tabs::
2567
2568    .. group-tab:: C++
2569
2570       .. doxygenfunction:: simgrid::s4u::Io::on_start_cb
2571       .. doxygenfunction:: simgrid::s4u::Io::on_this_start_cb
2572       .. doxygenfunction:: simgrid::s4u::Io::on_completion_cb
2573       .. doxygenfunction:: simgrid::s4u::Io::on_this_completion_cb
2574
2575       .. doxygenfunction:: simgrid::s4u::Io::on_suspended_cb
2576       .. doxygenfunction:: simgrid::s4u::Io::on_resumed_cb
2577       .. doxygenfunction:: simgrid::s4u::Io::on_veto_cb
2578
2579
2580 .. _API_s4u_Tasks:
2581
2582 ==========
2583 Tasks
2584 ==========
2585
2586 ==============
2587 class Task
2588 ==============
2589
2590 .. doxygenclass:: simgrid::s4u::Task
2591
2592 **Known subclasses:**
2593 :ref:`Communication Tasks <API_s4u_CommTask>`,
2594 :ref:`Executions Tasks <API_s4u_ExecTask>`,
2595 :ref:`I/O Tasks <API_s4u_IoTask>`.
2596 See also the :ref:`section on activities <s4u_Tasks>` above.
2597
2598 Basic management
2599 ----------------
2600
2601 .. tabs::
2602
2603    .. group-tab:: C++
2604
2605       .. code-block:: C++
2606
2607          #include <simgrid/s4u/Task.hpp>
2608
2609       .. doxygentypedef:: TaskPtr
2610
2611 Querying info
2612 -------------
2613
2614 .. tabs::
2615
2616    .. group-tab:: C++
2617
2618       .. doxygenfunction:: simgrid::s4u::Task::get_cname() const
2619       .. doxygenfunction:: simgrid::s4u::Task::get_name() const
2620       .. doxygenfunction:: simgrid::s4u::Task::get_count() const
2621       .. doxygenfunction:: simgrid::s4u::Task::get_amount() const
2622       .. doxygenfunction:: simgrid::s4u::Task::get_parallelism_degree() const
2623       .. doxygenfunction:: simgrid::s4u::Task::set_name(std::string name)
2624       .. doxygenfunction:: simgrid::s4u::Task::set_amount(double amount)
2625       .. doxygenfunction:: simgrid::s4u::Task::set_parallelism_degree(int n)
2626
2627 Life cycle
2628 ----------
2629
2630 .. tabs::
2631
2632    .. group-tab:: C++
2633       .. doxygenfunction:: simgrid::s4u::Task::enqueue_firings(int n)
2634
2635 Managing Dependencies
2636 ---------------------
2637 .. tabs::
2638
2639    .. group-tab:: C++
2640       .. doxygenfunction:: simgrid::s4u::Task::add_successor(TaskPtr t)
2641       .. doxygenfunction:: simgrid::s4u::Task::remove_successor(TaskPtr t)
2642       .. doxygenfunction:: simgrid::s4u::Task::remove_all_successors()
2643       .. doxygenfunction:: simgrid::s4u::Task::get_successors() const
2644
2645 Managing Tokens
2646 ---------------
2647 .. doxygenclass:: simgrid::s4u::Token
2648
2649 .. tabs::
2650
2651    .. group-tab:: C++
2652       .. doxygenfunction:: simgrid::s4u::Task::get_next_token_from(TaskPtr t)
2653       .. doxygenfunction:: simgrid::s4u::Task::set_token(std::shared_ptr<Token> token)
2654
2655 Signals
2656 -------
2657
2658 .. tabs::
2659
2660    .. group-tab:: C++
2661       .. doxygenfunction:: simgrid::s4u::Task::on_start_cb
2662       .. doxygenfunction:: simgrid::s4u::Task::on_this_start_cb
2663       .. doxygenfunction:: simgrid::s4u::Task::on_completion_cb
2664       .. doxygenfunction:: simgrid::s4u::Task::on_this_completion_cb
2665
2666 .. _API_s4u_CommTask:
2667
2668 =================
2669 ⁣  class CommTask
2670 =================
2671 .. tabs::
2672
2673    .. group-tab:: C++
2674
2675       .. doxygenclass:: simgrid::s4u::CommTask
2676
2677 Basic management
2678 ----------------
2679
2680 .. tabs::
2681
2682    .. group-tab:: C++
2683
2684       .. code-block:: C++
2685
2686          #include <simgrid/s4u/Task.hpp>
2687
2688       .. doxygentypedef:: CommTaskPtr
2689
2690 Querying info
2691 -------------
2692
2693 .. tabs::
2694
2695    .. group-tab:: C++
2696
2697       .. doxygenfunction:: simgrid::s4u::CommTask::get_source() const
2698       .. doxygenfunction:: simgrid::s4u::CommTask::get_destination() const
2699       .. doxygenfunction:: simgrid::s4u::CommTask::get_bytes() const
2700       .. doxygenfunction:: simgrid::s4u::CommTask::set_source(Host* source);
2701       .. doxygenfunction:: simgrid::s4u::CommTask::set_destination(Host* destination);
2702       .. doxygenfunction:: simgrid::s4u::CommTask::set_bytes(double bytes)
2703
2704
2705 .. _API_s4u_ExecTask:
2706
2707 =================
2708 ⁣  class ExecTask
2709 =================
2710 .. tabs::
2711
2712    .. group-tab:: C++
2713
2714       .. doxygenclass:: simgrid::s4u::ExecTask
2715
2716 Basic management
2717 ----------------
2718
2719 .. tabs::
2720
2721    .. group-tab:: C++
2722
2723       .. code-block:: C++
2724
2725          #include <simgrid/s4u/Task.hpp>
2726
2727       .. doxygentypedef:: ExecTaskPtr
2728
2729 Querying info
2730 -------------
2731
2732 .. tabs::
2733
2734    .. group-tab:: C++
2735
2736       .. doxygenfunction:: simgrid::s4u::ExecTask::get_host() const
2737       .. doxygenfunction:: simgrid::s4u::ExecTask::get_flops() const
2738       .. doxygenfunction:: simgrid::s4u::ExecTask::set_host(Host* host);
2739       .. doxygenfunction:: simgrid::s4u::ExecTask::set_flops(double flops);
2740
2741 .. _API_s4u_IoTask:
2742
2743 ================
2744 ⁣  class IoTask
2745 ================
2746 .. tabs::
2747
2748    .. group-tab:: C++
2749
2750       .. doxygenclass:: simgrid::s4u::IoTask
2751
2752 Basic management
2753 ----------------
2754
2755 .. tabs::
2756
2757    .. group-tab:: C++
2758
2759       .. code-block:: C++
2760
2761          #include <simgrid/s4u/Task.hpp>
2762
2763       .. doxygentypedef:: IoTaskPtr
2764
2765 Querying info
2766 -------------
2767
2768 .. tabs::
2769
2770    .. group-tab:: C++
2771
2772      .. doxygenfunction:: simgrid::s4u::IoTask::get_disk() const
2773      .. doxygenfunction:: simgrid::s4u::IoTask::get_bytes() const
2774      .. doxygenfunction:: simgrid::s4u::IoTask::get_op_type() const
2775      .. doxygenfunction:: simgrid::s4u::IoTask::set_disk(Disk* disk);
2776      .. doxygenfunction:: simgrid::s4u::IoTask::set_bytes(double bytes);
2777      .. doxygenfunction:: simgrid::s4u::IoTask::set_op_type(Io::OpType type);
2778
2779 .. _API_s4u_Synchronizations:
2780
2781 =======================
2782 Synchronization Objects
2783 =======================
2784
2785 .. _API_s4u_Mutex:
2786
2787 ==============
2788 ⁣  Mutex
2789 ==============
2790
2791 .. tabs::
2792
2793    .. group-tab:: C++
2794
2795       .. doxygenclass:: simgrid::s4u::Mutex
2796
2797    .. group-tab:: Python
2798
2799       .. autoclass:: simgrid.Mutex
2800
2801 Basic management
2802 ----------------
2803
2804    .. tabs::
2805
2806       .. group-tab:: C++
2807
2808          .. code-block:: C++
2809
2810             #include <simgrid/s4u/Mutex.hpp>
2811
2812          .. doxygentypedef:: MutexPtr
2813
2814          .. doxygenfunction:: simgrid::s4u::Mutex::create()
2815
2816       .. group-tab:: Python
2817
2818          .. code-block:: Python
2819
2820             from simgrid import Mutex
2821             mutex = Mutex()
2822
2823             # Use a context manager to acquire and automatically release the mutex
2824             # when leaving the scope.
2825             with mutex:
2826                 # Access shared resource ...
2827                 pass
2828
2829          .. automethod:: simgrid.Mutex.__init__
2830
2831       .. group-tab:: C
2832
2833          .. code-block:: C
2834
2835             #include <simgrid/mutex.h>
2836
2837          .. doxygentypedef:: sg_mutex_t
2838          .. cpp:type:: const s4u_Mutex* const_sg_mutex_t
2839
2840             Pointer to a constant mutex object.
2841
2842          .. doxygenfunction:: sg_mutex_init()
2843          .. doxygenfunction:: sg_mutex_destroy(const_sg_mutex_t mutex)
2844
2845 Locking
2846 -------
2847
2848    .. tabs::
2849
2850       .. group-tab:: C++
2851
2852          .. doxygenfunction:: simgrid::s4u::Mutex::lock()
2853          .. doxygenfunction:: simgrid::s4u::Mutex::try_lock()
2854          .. doxygenfunction:: simgrid::s4u::Mutex::unlock()
2855
2856       .. group-tab:: Python
2857
2858          .. automethod:: simgrid.Mutex.lock
2859          .. automethod:: simgrid.Mutex.try_lock
2860          .. automethod:: simgrid.Mutex.unlock
2861
2862       .. group-tab:: C
2863
2864          .. doxygenfunction:: sg_mutex_lock(sg_mutex_t mutex)
2865          .. doxygenfunction:: sg_mutex_try_lock(sg_mutex_t mutex)
2866          .. doxygenfunction:: sg_mutex_unlock(sg_mutex_t mutex)
2867
2868 .. _API_s4u_Barrier:
2869
2870 ================
2871 ⁣  Barrier
2872 ================
2873
2874 .. tabs::
2875
2876    .. group-tab:: C++
2877
2878       .. doxygenclass:: simgrid::s4u::Barrier
2879
2880    .. group-tab:: Python
2881
2882       .. autoclass:: simgrid.Barrier
2883
2884 .. tabs::
2885
2886    .. group-tab:: C++
2887
2888       .. code-block:: C++
2889
2890          #include <simgrid/s4u/Barrier.hpp>
2891
2892       .. doxygentypedef:: BarrierPtr
2893
2894       .. doxygenfunction:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
2895       .. doxygenfunction:: simgrid::s4u::Barrier::wait()
2896
2897    .. group-tab:: Python
2898
2899       .. code-block:: Python
2900
2901          from simgrid import Barrier
2902          barrier = Barrier(2)
2903
2904       .. automethod:: simgrid.Barrier.__init__
2905       .. automethod:: simgrid.Barrier.wait
2906
2907    .. group-tab:: C
2908
2909       .. code-block:: C
2910
2911          #include <simgrid/barrier.hpp>
2912
2913       .. doxygentypedef:: sg_bar_t
2914
2915       .. doxygenfunction:: sg_barrier_init(unsigned int count)
2916       .. doxygenfunction:: sg_barrier_destroy(sg_bar_t bar)
2917       .. doxygenfunction:: sg_barrier_wait(sg_bar_t bar)
2918
2919
2920 .. _API_s4u_ConditionVariable:
2921
2922 ==========================
2923 ⁣  Condition variable
2924 ==========================
2925
2926 .. doxygenclass:: simgrid::s4u::ConditionVariable
2927
2928 Basic management
2929 ----------------
2930
2931    .. tabs::
2932
2933       .. group-tab:: C++
2934
2935          .. code-block:: C++
2936
2937             #include <simgrid/s4u/ConditionVariable.hpp>
2938
2939          .. doxygentypedef:: ConditionVariablePtr
2940
2941          .. doxygenfunction:: simgrid::s4u::ConditionVariable::create()
2942
2943       .. group-tab:: C
2944
2945          .. code-block:: C
2946
2947             #include <simgrid/cond.h>
2948
2949          .. doxygentypedef:: sg_cond_t
2950          .. doxygentypedef:: const_sg_cond_t
2951          .. doxygenfunction:: sg_cond_init
2952          .. doxygenfunction:: sg_cond_destroy
2953
2954 Waiting and notifying
2955 ---------------------
2956
2957    .. tabs::
2958
2959       .. group-tab:: C++
2960
2961          .. doxygenfunction:: simgrid::s4u::ConditionVariable::notify_all()
2962          .. doxygenfunction:: simgrid::s4u::ConditionVariable::notify_one()
2963          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(s4u::MutexPtr lock)
2964          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< s4u::Mutex > &lock)
2965          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock, P pred)
2966          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration)
2967          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration, P pred)
2968          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration)
2969          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred)
2970          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time)
2971          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred)
2972          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time)
2973          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time, P pred)
2974
2975       .. group-tab:: C
2976
2977          .. doxygenfunction:: sg_cond_notify_all
2978          .. doxygenfunction:: sg_cond_notify_one
2979          .. doxygenfunction:: sg_cond_wait
2980          .. doxygenfunction:: sg_cond_wait_for
2981
2982 .. _API_s4u_Semaphore:
2983
2984 ==================
2985 ⁣  Semaphore
2986 ==================
2987
2988 .. tabs::
2989
2990    .. group-tab:: C++
2991
2992       .. doxygenclass:: simgrid::s4u::Semaphore
2993
2994    .. group-tab:: Python
2995
2996       .. autoclass:: simgrid.Semaphore
2997
2998 Basic management
2999 ----------------
3000
3001    .. tabs::
3002
3003       .. group-tab:: C++
3004
3005          .. code-block:: C++
3006
3007             #include <simgrid/s4u/Semaphore.hpp>
3008
3009          .. doxygentypedef:: SemaphorePtr
3010          .. doxygenfunction:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity)
3011
3012       .. group-tab:: Python
3013
3014          .. code-block:: Python
3015
3016             from simgrid import Semaphore
3017             semaphore = Semaphore(1)
3018             # Automatically acquire the semaphore, and release it after leaving the scope.
3019             with semaphore:
3020                 # Do something with the shared resource
3021                 pass
3022
3023          .. automethod:: simgrid.Semaphore.__init__
3024
3025       .. group-tab:: C
3026
3027          .. code-block:: C
3028
3029             #include <simgrid/semaphore.h>
3030
3031          .. doxygentypedef:: sg_sem_t
3032          .. cpp:type:: const s4u_Semaphore* const_sg_sem_t
3033
3034             Pointer to a constant semaphore object.
3035
3036          .. doxygenfunction:: sg_sem_init(int initial_value)
3037          .. doxygenfunction:: sg_sem_destroy(const_sg_sem_t sem)
3038
3039 Locking
3040 -------
3041
3042    .. tabs::
3043
3044       .. group-tab:: C++
3045
3046          .. doxygenfunction:: simgrid::s4u::Semaphore::acquire()
3047          .. doxygenfunction:: simgrid::s4u::Semaphore::acquire_timeout(double timeout)
3048          .. doxygenfunction:: simgrid::s4u::Semaphore::get_capacity() const
3049          .. doxygenfunction:: simgrid::s4u::Semaphore::release()
3050          .. doxygenfunction:: simgrid::s4u::Semaphore::would_block() const
3051
3052       .. group-tab:: Python
3053
3054          .. automethod:: simgrid.Semaphore.acquire
3055          .. automethod:: simgrid.Semaphore.acquire_timeout
3056          .. autoattribute:: simgrid.Semaphore.capacity
3057          .. automethod:: simgrid.Semaphore.release
3058          .. autoattribute:: simgrid.Semaphore.would_block
3059
3060       .. group-tab:: C
3061
3062          .. doxygenfunction:: sg_sem_acquire(sg_sem_t sem)
3063          .. doxygenfunction:: sg_sem_acquire_timeout(sg_sem_t sem, double timeout)
3064          .. doxygenfunction:: sg_sem_get_capacity(const_sg_sem_t sem)
3065          .. doxygenfunction:: sg_sem_release(sg_sem_t sem)
3066          .. doxygenfunction:: sg_sem_would_block(const_sg_sem_t sem)
3067
3068 ===============
3069 Error reporting
3070 ===============
3071
3072 .. tabs::
3073
3074    .. group-tab:: C++
3075
3076       .. doxygenclass:: simgrid::Exception
3077
3078       The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
3079
3080       .. doxygenclass:: simgrid::CancelException
3081       .. doxygenclass:: simgrid::HostFailureException
3082       .. doxygenclass:: simgrid::NetworkFailureException
3083       .. doxygenclass:: simgrid::StorageFailureException
3084       .. doxygenclass:: simgrid::TimeoutException
3085       .. doxygenclass:: simgrid::VmFailureException
3086
3087       The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
3088       exception go, so that the simulation stops. But you may want to catch them, for example when you launch
3089       SimGrid from a python notebook and want to handle the problem accordingly.
3090
3091       .. doxygenclass:: simgrid::AssertionError
3092       .. doxygenclass:: simgrid::ParseError
3093       .. doxygenclass:: simgrid::TracingError
3094
3095    .. group-tab:: Python
3096
3097       The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
3098
3099       .. autoclass:: simgrid.CancelException
3100       .. autoclass:: simgrid.HostFailureException
3101       .. autoclass:: simgrid.NetworkFailureException
3102       .. autoclass:: simgrid.StorageFailureException
3103       .. autoclass:: simgrid.TimeoutException
3104       .. autoclass:: simgrid.VmFailureException
3105
3106       The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
3107       exception go, so that the simulation stops. But you may want to catch them, for example when you launch
3108       SimGrid from a python notebook and want to handle the problem accordingly.
3109
3110       .. autoclass:: simgrid.AssertionError
3111
3112    .. group-tab:: C
3113
3114       .. doxygenenum:: sg_error_t
3115
3116
3117 .. |hr| raw:: html
3118
3119    <hr />