docs/source/app_s4u.rst

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