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