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