docs/source/app_s4u.rst

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