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