docs/source/app_s4u.rst

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