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