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