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