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