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 DVFS
1399 ----
1400
1401 .. tabs::
1402
1403    .. group-tab:: C++
1404
1405       .. doxygenfunction:: simgrid::s4u::Host::get_pstate() const
1406       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_count() const
1407       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_speed(unsigned long pstate_index) const
1408       .. doxygenfunction:: simgrid::s4u::Host::set_pstate(unsigned long pstate_index)
1409
1410    .. group-tab:: Python
1411
1412       .. autoattribute:: simgrid.Host.pstate
1413       .. autoattribute:: simgrid.Host.pstate_count
1414       .. automethod:: simgrid.Host.pstate_speed
1415
1416    .. group-tab:: C
1417
1418       .. doxygenfunction:: sg_host_get_available_speed(const_sg_host_t host)
1419       .. doxygenfunction:: sg_host_get_nb_pstates(const_sg_host_t host)
1420       .. doxygenfunction:: sg_host_get_pstate(const_sg_host_t host)
1421       .. doxygenfunction:: sg_host_get_pstate_speed(const_sg_host_t host, unsigned long pstate_index)
1422       .. doxygenfunction:: sg_host_set_pstate(sg_host_t host, unsigned long pstate)
1423
1424 Dynamic profiles
1425 ----------------
1426
1427 .. tabs::
1428
1429    .. group-tab:: C++
1430
1431       .. doxygenfunction:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p)
1432       .. doxygenfunction:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p)
1433
1434    .. group-tab:: Python
1435
1436       .. automethod:: simgrid.Host.set_speed_profile
1437       .. automethod:: simgrid.Host.set_state_profile
1438
1439 Execution
1440 ---------
1441
1442 .. tabs::
1443
1444    .. group-tab:: C++
1445
1446       .. doxygenfunction:: simgrid::s4u::Host::exec_async
1447       .. doxygenfunction:: simgrid::s4u::Host::execute(double flops) const
1448       .. doxygenfunction:: simgrid::s4u::Host::execute(double flops, double priority) const
1449
1450 Platform and routing
1451 --------------------
1452
1453 You can also start direct communications between two arbitrary hosts
1454 using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
1455
1456 .. tabs::
1457
1458    .. group-tab:: C++
1459
1460       .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() const
1461       .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const
1462       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const
1463       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::StandardLinkImpl * > &links, double *latency) const
1464       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, double read_bandwidth, double write_bandwidth)
1465       .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, const std::string& read_bandwidth, const std::string& write_bandwidth)
1466
1467    .. group-tab:: Python
1468
1469       .. autoattribute:: simgrid.Host.netpoint
1470       .. automethod:: simgrid.Host.create_disk
1471
1472       .. automethod:: simgrid.Host.route_to
1473
1474    .. group-tab:: C
1475
1476       .. doxygenfunction:: sg_host_get_route(const_sg_host_t from, const_sg_host_t to, xbt_dynar_t links)
1477       .. doxygenfunction:: sg_host_get_route_bandwidth(const_sg_host_t from, const_sg_host_t to)
1478       .. doxygenfunction:: sg_host_get_route_latency(const_sg_host_t from, const_sg_host_t to)
1479       .. doxygenfunction:: sg_host_sendto(sg_host_t from, sg_host_t to, double byte_amount)
1480
1481 Signals
1482 -------
1483
1484 .. tabs::
1485
1486    .. group-tab:: C++
1487
1488       .. doxygenfunction:: simgrid::s4u::Host::on_creation_cb
1489       .. doxygenfunction:: simgrid::s4u::Host::on_destruction_cb
1490       .. doxygenfunction:: simgrid::s4u::Host::on_speed_change_cb
1491       .. doxygenfunction:: simgrid::s4u::Host::on_state_change_cb
1492
1493 .. _API_s4u_Link:
1494
1495 =============
1496 ⁣  class Link
1497 =============
1498
1499 .. tabs::
1500
1501    .. group-tab:: C++
1502
1503       .. doxygenclass:: simgrid::s4u::Link
1504       .. doxygenclass:: simgrid::s4u::SplitDuplexLink
1505       .. doxygenclass:: simgrid::s4u::LinkInRoute
1506
1507
1508    .. group-tab:: Python
1509
1510       .. autoclass:: simgrid.Link
1511
1512 Basic management
1513 ----------------
1514
1515 .. tabs::
1516
1517    .. group-tab:: C++
1518
1519       .. code-block:: C++
1520
1521          #include <simgrid/s4u/Link.hpp>
1522
1523       Note that there is no LinkPtr type and that you cannot use the RAII
1524       idiom on hosts because SimGrid does not allow (yet) to create nor
1525       destroy resources once the simulation is started.
1526
1527       .. doxygenfunction:: simgrid::s4u::Link::seal()
1528
1529    .. group-tab:: Python
1530
1531       .. code:: Python
1532
1533          from simgrid import Link
1534
1535       .. automethod:: simgrid.Link.seal
1536
1537    .. group-tab:: C
1538
1539       .. code:: C
1540
1541          #include <simgrid/link.h>
1542
1543       .. doxygentypedef:: sg_link_t
1544       .. cpp:type:: const s4u_Link* const_sg_link_t
1545
1546          Pointer to a constant link object.
1547
1548 Retrieving links
1549 ----------------
1550
1551 .. tabs::
1552
1553    .. group-tab:: C++
1554
1555       See also :cpp:func:`simgrid::s4u::Engine::get_all_links`.
1556
1557       .. doxygenfunction:: simgrid::s4u::Link::by_name(const std::string &name)
1558       .. doxygenfunction:: simgrid::s4u::Link::by_name_or_null(const std::string &name)
1559
1560    .. group-tab:: Python
1561
1562       See also :py:attr:`simgrid.Engine.all_links`.
1563
1564       .. automethod:: simgrid.Link.by_name
1565       .. autoattribute:: simgrid.Link.name
1566
1567    .. group-tab:: C
1568
1569       .. doxygenfunction:: sg_link_by_name(const char *name)
1570       .. doxygenfunction:: sg_link_count()
1571       .. doxygenfunction:: sg_link_list()
1572
1573 Querying info
1574 --------------
1575
1576 .. tabs::
1577
1578    .. group-tab:: C++
1579
1580       .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const
1581       .. doxygenfunction:: simgrid::s4u::Link::get_cname() const
1582       .. doxygenfunction:: simgrid::s4u::Link::get_latency() const
1583       .. doxygenfunction:: simgrid::s4u::Link::get_name() const
1584       .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const
1585       .. doxygenfunction:: simgrid::s4u::Link::get_usage() const
1586       .. doxygenfunction:: simgrid::s4u::Link::is_used() const
1587
1588    .. group-tab:: Python
1589
1590       .. autoattribute:: simgrid.Link.bandwidth
1591       .. autoattribute:: simgrid.Link.latency
1592
1593    .. group-tab:: C
1594
1595       .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link)
1596       .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link)
1597       .. doxygenfunction:: sg_link_get_name(const_sg_link_t link)
1598       .. doxygenfunction:: sg_link_is_shared(const_sg_link_t link)
1599
1600 Modifying characteristics
1601 -------------------------
1602
1603 .. tabs::
1604
1605    .. group-tab:: C++
1606
1607       .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth(double value)
1608       .. doxygenfunction:: simgrid::s4u::Link::set_latency(double value)
1609       .. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value)
1610       .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
1611       .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
1612
1613    .. group-tab:: Python
1614
1615       .. automethod:: simgrid.Link.set_bandwidth
1616       .. automethod:: simgrid.Link.set_latency
1617       .. automethod:: simgrid.Link.set_concurrency_limit
1618       .. automethod:: simgrid.Link.set_sharing_policy
1619
1620    .. group-tab:: C
1621
1622       .. doxygenfunction:: sg_link_set_bandwidth(sg_link_t link, double value)
1623       .. doxygenfunction:: sg_link_set_latency(sg_link_t link, double value)
1624
1625 User data and properties
1626 ------------------------
1627
1628 .. tabs::
1629
1630    .. group-tab:: C++
1631
1632       .. doxygenfunction:: simgrid::s4u::Link::get_property(const std::string &key) const
1633       .. doxygenfunction:: simgrid::s4u::Link::set_property(const std::string &key, const std::string &value)
1634
1635    .. group-tab:: C
1636
1637       .. doxygenfunction:: sg_link_get_data(const_sg_link_t link)
1638       .. doxygenfunction:: sg_link_set_data(sg_link_t link, void *data)
1639
1640 On/Off
1641 ------
1642
1643 .. tabs::
1644
1645    .. group-tab:: C++
1646
1647       See also :cpp:func:`simgrid::s4u::Link::set_state_profile`.
1648
1649       .. doxygenfunction:: simgrid::s4u::Link::is_on() const
1650       .. doxygenfunction:: simgrid::s4u::Link::turn_off()
1651       .. doxygenfunction:: simgrid::s4u::Link::turn_on()
1652
1653    .. group-tab:: Python
1654
1655       See also :py:func:`simgrid.Link.set_state_profile`.
1656
1657       .. automethod:: simgrid.Link.is_on
1658       .. automethod:: simgrid.Link.turn_off
1659       .. automethod:: simgrid.Link.turn_on
1660
1661 Dynamic profiles
1662 ----------------
1663
1664 See :ref:`howto_churn` for more details.
1665
1666 .. tabs::
1667
1668    .. group-tab:: C++
1669
1670       .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth_profile(kernel::profile::Profile *profile)
1671       .. doxygenfunction:: simgrid::s4u::Link::set_latency_profile(kernel::profile::Profile *profile)
1672       .. doxygenfunction:: simgrid::s4u::Link::set_state_profile(kernel::profile::Profile *profile)
1673
1674    .. group-tab:: Python
1675
1676       .. automethod:: simgrid.Link.set_bandwidth_profile
1677       .. automethod:: simgrid.Link.set_latency_profile
1678       .. automethod:: simgrid.Link.set_state_profile
1679
1680 WIFI links
1681 ----------
1682
1683 .. tabs::
1684
1685    .. group-tab:: C++
1686
1687       .. doxygenfunction:: simgrid::s4u::Link::set_host_wifi_rate
1688
1689    .. group-tab:: Python
1690
1691       .. automethod:: simgrid.Link.set_host_wifi_rate
1692
1693 Signals
1694 -------
1695
1696 .. tabs::
1697
1698    .. group-tab:: C++
1699
1700       .. doxygenfunction:: simgrid::s4u::Link::on_bandwidth_change_cb
1701       .. doxygenfunction:: simgrid::s4u::Link::on_communication_state_change_cb
1702       .. doxygenfunction:: simgrid::s4u::Link::on_creation_cb
1703       .. doxygenfunction:: simgrid::s4u::Link::on_destruction_cb
1704       .. doxygenfunction:: simgrid::s4u::Link::on_state_change_cb
1705
1706 .. _API_s4u_NetZone:
1707
1708 ================
1709 ⁣  class NetZone
1710 ================
1711
1712 .. tabs::
1713
1714    .. group-tab:: C++
1715
1716       .. doxygenclass:: simgrid::s4u::NetZone
1717
1718    .. group-tab:: Python
1719
1720       .. autoclass:: simgrid.NetZone
1721
1722 Basic management
1723 ----------------
1724
1725 .. tabs::
1726
1727    .. group-tab:: C++
1728
1729       .. code-block:: C++
1730
1731          #include <simgrid/s4u/NetZone.hpp>
1732
1733       Note that there is no NetZonePtr type and that you cannot use the RAII
1734       idiom on network zones because SimGrid does not allow (yet) to create nor
1735       destroy resources once the simulation is started.
1736
1737       .. doxygenfunction:: simgrid::s4u::NetZone::seal
1738
1739    .. group-tab:: Python
1740
1741       .. code:: Python
1742
1743          from simgrid import NetZone
1744
1745       .. automethod:: simgrid.NetZone.seal
1746
1747    .. group-tab:: C
1748
1749       .. code:: C
1750
1751          #include <simgrid/zone.h>
1752
1753       .. doxygentypedef:: sg_netzone_t
1754       .. cpp:type:: const s4u_NetZone* const_sg_netzone_t
1755
1756          Pointer to a constant network zone object.
1757
1758 Retrieving zones
1759 ----------------
1760
1761 .. tabs::
1762
1763    .. group-tab:: C++
1764
1765       See :cpp:func:`simgrid::s4u::Engine::get_netzone_root`,
1766       :cpp:func:`simgrid::s4u::Engine::netzone_by_name_or_null` and
1767       :cpp:func:`simgrid::s4u::Engine::get_filtered_netzones`.
1768
1769    .. group-tab:: C
1770
1771       .. doxygenfunction:: sg_zone_get_by_name(const char *name)
1772       .. doxygenfunction:: sg_zone_get_root()
1773
1774 Querying info
1775 --------------
1776
1777 .. tabs::
1778
1779    .. group-tab:: C++
1780
1781       .. doxygenfunction:: simgrid::s4u::NetZone::get_cname() const
1782       .. doxygenfunction:: simgrid::s4u::NetZone::get_name() const
1783       .. doxygenfunction:: simgrid::s4u::NetZone::get_netpoint()
1784
1785    .. group-tab:: Python
1786
1787       .. autoattribute:: simgrid.NetZone.name
1788       .. autoattribute:: simgrid.NetZone.netpoint
1789
1790    .. group-tab:: C
1791
1792       .. doxygenfunction:: sg_zone_get_name(const_sg_netzone_t zone)
1793
1794 User data and properties
1795 ------------------------
1796
1797 .. tabs::
1798
1799    .. group-tab:: C++
1800
1801       .. doxygenfunction:: simgrid::s4u::NetZone::get_properties() const
1802       .. doxygenfunction:: simgrid::s4u::NetZone::get_property(const std::string &key) const
1803       .. doxygenfunction:: simgrid::s4u::NetZone::set_property(const std::string &key, const std::string &value)
1804
1805    .. group-tab:: Python
1806
1807       .. automethod:: simgrid.NetZone.set_property
1808
1809    .. group-tab:: C
1810
1811       .. doxygenfunction:: sg_zone_get_property_value(const_sg_netzone_t as, const char *name)
1812       .. doxygenfunction:: sg_zone_set_property_value(sg_netzone_t netzone, const char *name, const char *value)
1813
1814 Retrieving components
1815 ---------------------
1816
1817 .. tabs::
1818
1819    .. group-tab:: C++
1820
1821       .. doxygenfunction:: simgrid::s4u::NetZone::get_all_hosts() const
1822       .. doxygenfunction:: simgrid::s4u::NetZone::get_host_count() const
1823
1824    .. group-tab:: C
1825
1826       .. doxygenfunction:: sg_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
1827
1828 Routing data
1829 ------------
1830
1831 .. tabs::
1832
1833    .. group-tab:: C++
1834
1835       .. doxygenfunction:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm)
1836       .. doxygenfunction:: simgrid::s4u::NetZone::add_route
1837       .. doxygenfunction:: simgrid::s4u::NetZone::add_bypass_route
1838       .. doxygenfunction:: simgrid::s4u::NetZone::get_children() const
1839       .. doxygenfunction:: simgrid::s4u::NetZone::get_parent() const
1840       .. doxygenfunction:: simgrid::s4u::NetZone::set_parent(const NetZone* parent)
1841
1842    .. group-tab:: Python
1843
1844       .. automethod:: simgrid.NetZone.add_route
1845       .. automethod:: simgrid.NetZone.set_parent
1846
1847    .. group-tab:: C
1848
1849       .. doxygenfunction:: sg_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
1850
1851 Signals
1852 -------
1853
1854 .. tabs::
1855
1856   .. group-tab:: C++
1857
1858      .. doxygenfunction:: simgrid::s4u::NetZone::on_creation_cb
1859      .. doxygenfunction:: simgrid::s4u::NetZone::on_seal_cb
1860
1861 Creating resources
1862 ------------------
1863
1864 Zones
1865 ^^^^^
1866 .. tabs::
1867
1868   .. group-tab:: C++
1869
1870      .. doxygenfunction:: simgrid::s4u::create_full_zone
1871      .. doxygenfunction:: simgrid::s4u::create_empty_zone
1872      .. doxygenfunction:: simgrid::s4u::create_star_zone
1873      .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone
1874      .. doxygenfunction:: simgrid::s4u::create_floyd_zone
1875      .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone
1876      .. doxygenfunction:: simgrid::s4u::create_wifi_zone
1877      .. doxygenfunction:: simgrid::s4u::create_torus_zone
1878      .. doxygenfunction:: simgrid::s4u::create_fatTree_zone
1879      .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone
1880
1881   .. group-tab:: Python
1882
1883      .. automethod:: simgrid.NetZone.create_full_zone
1884      .. automethod:: simgrid.NetZone.create_empty_zone
1885      .. automethod:: simgrid.NetZone.create_star_zone
1886      .. automethod:: simgrid.NetZone.create_dijkstra_zone
1887      .. automethod:: simgrid.NetZone.create_floyd_zone
1888      .. automethod:: simgrid.NetZone.create_vivaldi_zone
1889      .. automethod:: simgrid.NetZone.create_wifi_zone
1890      .. automethod:: simgrid.NetZone.create_torus_zone
1891      .. automethod:: simgrid.NetZone.create_fatTree_zone
1892      .. automethod:: simgrid.NetZone.create_dragonfly_zone
1893
1894 Hosts
1895 ^^^^^
1896
1897 .. tabs::
1898
1899   .. group-tab:: C++
1900
1901      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::vector<double>& speed_per_pstate)
1902      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, double speed)
1903      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::vector<std::string>& speed_per_pstate)
1904      .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::string& speed)
1905
1906   .. group-tab:: Python
1907
1908      .. automethod:: simgrid.NetZone.create_host
1909
1910 Links
1911 ^^^^^
1912
1913 .. tabs::
1914
1915   .. group-tab:: C++
1916
1917      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<double>& bandwidths)
1918      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, double bandwidth)
1919      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<std::string>& bandwidthds)
1920      .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::string& bandwidth)
1921      .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, const std::string& bandwidth)
1922      .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, double bandwidth)
1923
1924   .. group-tab:: Python
1925
1926      .. automethod:: simgrid.NetZone.create_link
1927      .. automethod:: simgrid.NetZone.create_split_duplex_link
1928
1929 Router
1930 ^^^^^^
1931
1932 .. tabs::
1933
1934   .. group-tab:: C++
1935
1936      .. doxygenfunction:: simgrid::s4u::NetZone::create_router(const std::string& name)
1937
1938   .. group-tab:: Python
1939
1940      .. automethod:: simgrid.NetZone.create_router
1941
1942 .. _API_s4u_VirtualMachine:
1943
1944 =======================
1945 ⁣  class VirtualMachine
1946 =======================
1947
1948
1949 .. doxygenclass:: simgrid::s4u::VirtualMachine
1950
1951 Basic management
1952 ----------------
1953 .. tabs::
1954
1955    .. group-tab:: C++
1956
1957       .. code-block:: C++
1958
1959          #include <simgrid/s4u/VirtualMachine.hpp>
1960
1961       Note that there is no VirtualMachinePtr type, and that you cannot use the RAII
1962       idiom on virtual machines. There is no good reason for that and should change in the future.
1963
1964    .. group-tab:: C
1965
1966       .. code:: C
1967
1968          #include <simgrid/vm.h>
1969
1970       .. doxygentypedef:: sg_vm_t
1971       .. cpp:type:: const s4u_VirtualMachine* const_sg_vm_t
1972
1973          Pointer to a constant virtual machine object.
1974
1975 Creating VMs
1976 ------------
1977
1978 .. tabs::
1979
1980    .. group-tab:: C++
1981
1982       .. doxygenfunction:: simgrid::s4u::Host::create_vm(const std::string &name, int core_amount)
1983       .. doxygenfunction:: simgrid::s4u::Host::create_vm(const std::string &name, int core_amount, size_t ramsize)
1984       .. doxygenfunction:: simgrid::s4u::VirtualMachine::destroy
1985
1986    .. group-tab:: C
1987
1988       .. doxygenfunction:: sg_vm_create_core
1989       .. doxygenfunction:: sg_vm_create_multicore
1990       .. doxygenfunction:: sg_vm_destroy
1991
1992 Querying info
1993 --------------
1994
1995 .. tabs::
1996
1997    .. group-tab:: C++
1998
1999       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_pm() const
2000       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_ramsize() const
2001       .. doxygenfunction:: simgrid::s4u::VirtualMachine::get_state() const
2002
2003       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_bound(double bound)
2004       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_pm(Host *pm)
2005       .. doxygenfunction:: simgrid::s4u::VirtualMachine::set_ramsize(size_t ramsize)
2006
2007    .. group-tab:: C
2008
2009       .. doxygenfunction:: sg_vm_get_ramsize(const_sg_vm_t vm)
2010       .. doxygenfunction:: sg_vm_set_bound(sg_vm_t vm, double bound)
2011       .. doxygenfunction:: sg_vm_set_ramsize(sg_vm_t vm, size_t size)
2012
2013       .. doxygenfunction:: sg_vm_get_name
2014       .. doxygenfunction:: sg_vm_get_pm
2015       .. doxygenfunction:: sg_vm_is_created
2016       .. doxygenfunction:: sg_vm_is_running
2017       .. doxygenfunction:: sg_vm_is_suspended
2018
2019 Life cycle
2020 ----------
2021
2022 .. tabs::
2023
2024    .. group-tab:: C++
2025
2026       .. doxygenfunction:: simgrid::s4u::VirtualMachine::resume()
2027       .. doxygenfunction:: simgrid::s4u::VirtualMachine::shutdown()
2028       .. doxygenfunction:: simgrid::s4u::VirtualMachine::start()
2029       .. doxygenfunction:: simgrid::s4u::VirtualMachine::suspend()
2030
2031    .. group-tab:: C
2032
2033       .. doxygenfunction:: sg_vm_start
2034       .. doxygenfunction:: sg_vm_suspend
2035       .. doxygenfunction:: sg_vm_resume
2036       .. doxygenfunction:: sg_vm_shutdown
2037
2038 Signals
2039 -------
2040
2041 .. tabs::
2042
2043    .. group-tab:: C++
2044
2045       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_creation_cb
2046       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_destruction_cb
2047       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_end_cb
2048       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_start_cb
2049       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_resume_cb
2050       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_shutdown_cb
2051       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_start_cb
2052       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_started_cb
2053       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_suspend_cb
2054
2055 .. _API_s4u_Activity:
2056
2057 ==========
2058 Activities
2059 ==========
2060
2061 ==============
2062 class Activity
2063 ==============
2064
2065 .. doxygenclass:: simgrid::s4u::Activity
2066
2067 **Known subclasses:**
2068 :ref:`Communications <API_s4u_Comm>` (started on Mailboxes and consuming links),
2069 :ref:`Executions <API_s4u_Exec>` (started on Host and consuming CPU resources)
2070 :ref:`I/O <API_s4u_Io>` (started on and consuming disks).
2071 See also the :ref:`section on activities <s4u_Activities>` above.
2072
2073 Basic management
2074 ----------------
2075
2076 .. tabs::
2077
2078    .. group-tab:: C++
2079
2080       .. code-block:: C++
2081
2082          #include <simgrid/s4u/Activity.hpp>
2083
2084       .. doxygentypedef:: ActivityPtr
2085
2086 Querying info
2087 -------------
2088
2089 .. tabs::
2090
2091    .. group-tab:: C++
2092
2093       .. doxygenfunction:: simgrid::s4u::Activity::get_cname
2094       .. doxygenfunction:: simgrid::s4u::Activity::get_name
2095       .. doxygenfunction:: simgrid::s4u::Activity::get_remaining() const
2096       .. doxygenfunction:: simgrid::s4u::Activity::get_state() const
2097       .. doxygenfunction:: simgrid::s4u::Activity::set_remaining(double remains)
2098       .. doxygenfunction:: simgrid::s4u::Activity::set_state(Activity::State state)
2099
2100
2101 Activities life cycle
2102 ---------------------
2103
2104 .. tabs::
2105
2106    .. group-tab:: C++
2107
2108       .. doxygenfunction:: simgrid::s4u::Activity::start
2109       .. doxygenfunction:: simgrid::s4u::Activity::cancel
2110       .. doxygenfunction:: simgrid::s4u::Activity::test
2111       .. doxygenfunction:: simgrid::s4u::Activity::wait
2112       .. doxygenfunction:: simgrid::s4u::Activity::wait_for
2113       .. doxygenfunction:: simgrid::s4u::Activity::wait_until(double time_limit)
2114       .. doxygenfunction:: simgrid::s4u::Activity::vetoable_start()
2115
2116 Suspending and resuming an activity
2117 -----------------------------------
2118
2119 .. tabs::
2120
2121    .. group-tab:: C++
2122
2123       .. doxygenfunction:: simgrid::s4u::Activity::suspend
2124       .. doxygenfunction:: simgrid::s4u::Activity::resume
2125       .. doxygenfunction:: simgrid::s4u::Activity::is_suspended
2126
2127 Signals
2128 -------
2129
2130 .. tabs::
2131
2132    .. group-tab:: C++
2133
2134       .. doxygenfunction:: simgrid::s4u::Activity::on_completion_cb
2135       .. doxygenfunction:: simgrid::s4u::Activity::on_suspended_cb
2136       .. doxygenfunction:: simgrid::s4u::Activity::on_resumed_cb
2137
2138 .. _API_s4u_Comm:
2139
2140 =============
2141 ⁣  class Comm
2142 =============
2143
2144 .. tabs::
2145
2146    .. group-tab:: C++
2147
2148       .. doxygenclass:: simgrid::s4u::Comm
2149
2150    .. group-tab:: Python
2151
2152       .. autoclass:: simgrid.Comm
2153
2154 Basic management
2155 ----------------
2156
2157 .. tabs::
2158
2159    .. group-tab:: C++
2160
2161       .. code-block:: C++
2162
2163          #include <simgrid/s4u/Comm.hpp>
2164
2165       .. doxygentypedef:: CommPtr
2166
2167    .. group-tab:: Python
2168
2169       .. code:: Python
2170
2171          from simgrid import Comm
2172
2173    .. group-tab:: c
2174
2175       .. code:: c
2176
2177          #include <simgrid/comm.h>
2178
2179       .. doxygentypedef:: sg_comm_t
2180
2181 Querying info
2182 -------------
2183
2184 .. tabs::
2185
2186    .. group-tab:: C++
2187
2188       .. doxygenfunction:: simgrid::s4u::Comm::get_dst_data_size() const
2189       .. doxygenfunction:: simgrid::s4u::Comm::get_mailbox() const
2190       .. doxygenfunction:: simgrid::s4u::Comm::get_sender() const
2191       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff)
2192       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size)
2193       .. doxygenfunction:: simgrid::s4u::Comm::detach()
2194       .. doxygenfunction:: simgrid::s4u::Comm::detach(const std::function<void(void*)>& clean_function)
2195       .. doxygenfunction:: simgrid::s4u::Comm::set_payload_size(uint64_t bytes)
2196       .. doxygenfunction:: simgrid::s4u::Comm::set_rate(double rate)
2197       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff)
2198       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size)
2199       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data_size(size_t size)
2200
2201    .. group-tab:: Python
2202
2203       .. autoattribute:: simgrid.Comm.dst_data_size
2204       .. autoattribute:: simgrid.Comm.mailbox
2205       .. autoattribute:: simgrid.Comm.sender
2206       .. autoattribute:: simgrid.Comm.state_str
2207       .. automethod:: simgrid.Comm.detach
2208       .. automethod:: simgrid.Comm.set_payload_size
2209       .. automethod:: simgrid.Comm.set_rate
2210
2211 Life cycle
2212 ----------
2213
2214 Most communications are created using :ref:`s4u_mailbox`, but you can
2215 also start direct communications as shown below.
2216
2217 .. tabs::
2218
2219    .. group-tab:: C++
2220
2221       .. doxygenfunction:: simgrid::s4u::Comm::sendto
2222       .. doxygenfunction:: simgrid::s4u::Comm::sendto_init()
2223       .. doxygenfunction:: simgrid::s4u::Comm::sendto_init(Host *from, Host *to)
2224       .. doxygenfunction:: simgrid::s4u::Comm::sendto_async
2225
2226       .. doxygenfunction:: simgrid::s4u::Comm::cancel
2227       .. doxygenfunction:: simgrid::s4u::Comm::start
2228       .. doxygenfunction:: simgrid::s4u::Comm::test
2229       .. doxygenfunction:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr >& comms)
2230       .. doxygenfunction:: simgrid::s4u::Comm::wait
2231       .. doxygenfunction:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr >& comms)
2232       .. doxygenfunction:: simgrid::s4u::Comm::wait_all_for(const std::vector< CommPtr >& comms, double timeout)
2233       .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr >& comms)
2234       .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr >& comms, double timeout)
2235       .. doxygenfunction:: simgrid::s4u::Comm::wait_for
2236       .. doxygenfunction:: simgrid::s4u::Comm::wait_until
2237
2238    .. group-tab:: Python
2239
2240       .. automethod:: simgrid.Comm.sendto
2241       .. automethod:: simgrid.Comm.sendto_init
2242       .. automethod:: simgrid.Comm.sendto_async
2243
2244       .. automethod:: simgrid.Comm.cancel
2245       .. automethod:: simgrid.Comm.start
2246       .. automethod:: simgrid.Comm.test
2247       .. automethod:: simgrid.Comm.test_any
2248       .. automethod:: simgrid.Comm.wait
2249       .. automethod:: simgrid.Comm.wait_for
2250       .. automethod:: simgrid.Comm.wait_all
2251       .. automethod:: simgrid.Comm.wait_all_for
2252       .. automethod:: simgrid.Comm.wait_any
2253       .. automethod:: simgrid.Comm.wait_any_for
2254       .. automethod:: simgrid.Comm.wait_until
2255
2256    .. group-tab:: C
2257
2258       .. doxygenfunction:: sg_comm_test
2259       .. doxygenfunction:: sg_comm_wait
2260       .. doxygenfunction:: sg_comm_wait_all
2261       .. doxygenfunction:: sg_comm_wait_any
2262
2263 Signals
2264 -------
2265
2266 .. tabs::
2267
2268    .. group-tab:: C++
2269
2270       .. doxygenfunction:: simgrid::s4u::Comm::on_start_cb
2271       .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb
2272       .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb
2273       .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb
2274
2275 .. _API_s4u_Exec:
2276
2277 =============
2278 ⁣  class Exec
2279 =============
2280
2281 .. tabs::
2282
2283    .. group-tab:: C++
2284
2285       .. doxygenclass:: simgrid::s4u::Exec
2286
2287    .. group-tab:: Python
2288
2289       .. autoclass:: simgrid.Exec
2290
2291 Basic management
2292 ----------------
2293
2294 .. tabs::
2295
2296    .. group-tab:: C++
2297
2298       .. code-block:: C++
2299
2300          #include <simgrid/s4u/Exec.hpp>
2301
2302       .. doxygentypedef:: ExecPtr
2303
2304    .. group-tab:: Python
2305
2306       .. code:: Python
2307
2308          from simgrid import Exec
2309
2310    .. group-tab:: C
2311
2312       .. code-block:: C
2313
2314          #include <simgrid/exec.h>
2315
2316       .. doxygentypedef:: sg_exec_t
2317       .. doxygentypedef:: const_sg_exec_t
2318
2319 Querying info
2320 -------------
2321
2322 .. tabs::
2323
2324    .. group-tab:: C++
2325
2326       .. doxygenfunction:: simgrid::s4u::Exec::get_cost() const
2327       .. doxygenfunction:: simgrid::s4u::Exec::get_finish_time() const
2328       .. doxygenfunction:: simgrid::s4u::Exec::get_host() const
2329       .. doxygenfunction:: simgrid::s4u::Exec::get_host_number() const
2330       .. doxygenfunction:: simgrid::s4u::Exec::get_remaining
2331       .. doxygenfunction:: simgrid::s4u::Exec::get_remaining_ratio
2332       .. doxygenfunction:: simgrid::s4u::Exec::get_start_time() const
2333       .. doxygenfunction:: simgrid::s4u::Exec::set_bound(double bound)
2334       .. doxygenfunction:: simgrid::s4u::Exec::set_host
2335       .. doxygenfunction:: simgrid::s4u::Exec::set_priority(double priority)
2336
2337    .. group-tab:: Python
2338
2339       .. autoattribute:: simgrid.Exec.host
2340       .. autoattribute:: simgrid.Exec.remaining
2341       .. autoattribute:: simgrid.Exec.remaining_ratio
2342
2343    .. group-tab:: C
2344
2345       .. doxygenfunction:: sg_exec_set_bound(sg_exec_t exec, double bound)
2346       .. doxygenfunction:: sg_exec_get_name(const_sg_exec_t exec)
2347       .. doxygenfunction:: sg_exec_set_name(sg_exec_t exec, const char* name)
2348       .. doxygenfunction:: sg_exec_set_host(sg_exec_t exec, sg_host_t new_host)
2349       .. doxygenfunction:: sg_exec_get_remaining(const_sg_exec_t exec)
2350       .. doxygenfunction:: sg_exec_get_remaining_ratio(const_sg_exec_t exec)
2351
2352 Life cycle
2353 ----------
2354
2355 .. tabs::
2356
2357    .. group-tab:: C++
2358
2359       .. doxygenfunction:: simgrid::s4u::Exec::cancel
2360       .. doxygenfunction:: simgrid::s4u::Exec::start
2361       .. doxygenfunction:: simgrid::s4u::Exec::test
2362       .. doxygenfunction:: simgrid::s4u::Exec::wait
2363       .. doxygenfunction:: simgrid::s4u::Exec::wait_any(const std::vector< ExecPtr >& execs)
2364       .. doxygenfunction:: simgrid::s4u::Exec::wait_any_for(const std::vector< ExecPtr >& execs, double timeout)
2365       .. doxygenfunction:: simgrid::s4u::Exec::wait_for
2366
2367    .. group-tab:: Python
2368
2369        .. automethod:: simgrid.Exec.cancel
2370        .. automethod:: simgrid.Exec.start
2371        .. automethod:: simgrid.Exec.test
2372        .. automethod:: simgrid.Exec.wait
2373
2374    .. group-tab:: C
2375
2376        .. doxygenfunction:: sg_exec_start(sg_exec_t exec)
2377        .. doxygenfunction:: sg_exec_cancel(sg_exec_t exec);
2378        .. doxygenfunction:: sg_exec_test(sg_exec_t exec);
2379        .. doxygenfunction:: sg_exec_wait(sg_exec_t exec);
2380        .. doxygenfunction:: sg_exec_wait_for(sg_exec_t exec, double timeout);
2381        .. doxygenfunction:: sg_exec_wait_any_for(sg_exec_t* execs, size_t count, double timeout);
2382        .. doxygenfunction:: sg_exec_wait_any(sg_exec_t* execs, size_t count);
2383
2384 Signals
2385 -------
2386
2387 .. tabs::
2388
2389    .. group-tab:: C++
2390
2391       .. doxygenfunction:: simgrid::s4u::Exec::on_start_cb
2392       .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb
2393
2394 .. _API_s4u_Io:
2395
2396 ===========
2397 ⁣  class Io
2398 ===========
2399
2400 .. tabs::
2401
2402    .. group-tab:: C++
2403
2404       .. doxygenclass:: simgrid::s4u::Io
2405
2406    .. group-tab:: Python
2407
2408       .. autoclass:: simgrid.Io
2409
2410 Basic management
2411 ----------------
2412
2413 .. tabs::
2414
2415    .. group-tab:: C++
2416
2417       .. code-block:: C++
2418
2419          #include <simgrid/s4u/Io.hpp>
2420
2421       .. doxygentypedef:: IoPtr
2422
2423 Querying info
2424 -------------
2425
2426 .. tabs::
2427
2428    .. group-tab:: C++
2429
2430       .. doxygenfunction:: simgrid::s4u::Io::get_performed_ioops() const
2431       .. doxygenfunction:: simgrid::s4u::Io::get_remaining
2432
2433 Life cycle
2434 ----------
2435
2436 .. tabs::
2437
2438    .. group-tab:: C++
2439
2440       .. doxygenfunction:: simgrid::s4u::Io::cancel
2441       .. doxygenfunction:: simgrid::s4u::Io::start
2442       .. doxygenfunction:: simgrid::s4u::Io::test
2443       .. doxygenfunction:: simgrid::s4u::Io::wait
2444       .. doxygenfunction:: simgrid::s4u::Io::wait_for
2445       .. doxygenfunction:: simgrid::s4u::Io::wait_any(const std::vector<IoPtr> &ios)
2446       .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector<IoPtr> &ios, double timeout)
2447
2448    .. group-tab:: Python
2449
2450       .. automethod:: simgrid.Io.test
2451       .. automethod:: simgrid.Io.wait
2452       .. automethod:: simgrid.Io.wait_any_for
2453       .. automethod:: simgrid.Io.wait_any
2454
2455 Signals
2456 -------
2457
2458 .. tabs::
2459
2460    .. group-tab:: C++
2461
2462       .. doxygenfunction:: simgrid::s4u::Io::on_start_cb
2463       .. doxygenfunction:: simgrid::s4u::Io::on_completion_cb
2464
2465 .. _API_s4u_Synchronizations:
2466
2467 =======================
2468 Synchronization Objects
2469 =======================
2470
2471 .. _API_s4u_Mutex:
2472
2473 ==============
2474 ⁣  Mutex
2475 ==============
2476
2477 .. tabs::
2478
2479    .. group-tab:: C++
2480
2481       .. doxygenclass:: simgrid::s4u::Mutex
2482
2483    .. group-tab:: Python
2484
2485       .. autoclass:: simgrid.Mutex
2486
2487 Basic management
2488 ----------------
2489
2490    .. tabs::
2491
2492       .. group-tab:: C++
2493
2494          .. code-block:: C++
2495
2496             #include <simgrid/s4u/Mutex.hpp>
2497
2498          .. doxygentypedef:: MutexPtr
2499
2500          .. doxygenfunction:: simgrid::s4u::Mutex::create()
2501
2502       .. group-tab:: Python
2503
2504          .. code-block:: Python
2505
2506             from simgrid import Mutex
2507             mutex = Mutex()
2508
2509             # Use a context manager to acquire and automatically release the mutex
2510             # when leaving the scope.
2511             with mutex:
2512                 # Access shared resource ...
2513                 pass
2514
2515          .. automethod:: simgrid.Mutex.__init__
2516
2517       .. group-tab:: C
2518
2519          .. code-block:: C
2520
2521             #include <simgrid/mutex.h>
2522
2523          .. doxygentypedef:: sg_mutex_t
2524          .. cpp:type:: const s4u_Mutex* const_sg_mutex_t
2525
2526             Pointer to a constant mutex object.
2527
2528          .. doxygenfunction:: sg_mutex_init()
2529          .. doxygenfunction:: sg_mutex_destroy(const_sg_mutex_t mutex)
2530
2531 Locking
2532 -------
2533
2534    .. tabs::
2535
2536       .. group-tab:: C++
2537
2538          .. doxygenfunction:: simgrid::s4u::Mutex::lock()
2539          .. doxygenfunction:: simgrid::s4u::Mutex::try_lock()
2540          .. doxygenfunction:: simgrid::s4u::Mutex::unlock()
2541
2542       .. group-tab:: Python
2543
2544          .. automethod:: simgrid.Mutex.lock
2545          .. automethod:: simgrid.Mutex.try_lock
2546          .. automethod:: simgrid.Mutex.unlock
2547
2548       .. group-tab:: C
2549
2550          .. doxygenfunction:: sg_mutex_lock(sg_mutex_t mutex)
2551          .. doxygenfunction:: sg_mutex_try_lock(sg_mutex_t mutex)
2552          .. doxygenfunction:: sg_mutex_unlock(sg_mutex_t mutex)
2553
2554 .. _API_s4u_Barrier:
2555
2556 ================
2557 ⁣  Barrier
2558 ================
2559
2560 .. tabs::
2561
2562    .. group-tab:: C++
2563
2564       .. doxygenclass:: simgrid::s4u::Barrier
2565
2566    .. group-tab:: Python
2567
2568       .. autoclass:: simgrid.Barrier
2569
2570 .. tabs::
2571
2572    .. group-tab:: C++
2573
2574       .. code-block:: C++
2575
2576          #include <simgrid/s4u/Barrier.hpp>
2577
2578       .. doxygentypedef:: BarrierPtr
2579
2580       .. doxygenfunction:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
2581       .. doxygenfunction:: simgrid::s4u::Barrier::wait()
2582
2583    .. group-tab:: Python
2584
2585       .. code-block:: Python
2586
2587          from simgrid import Barrier
2588          barrier = Barrier(2)
2589
2590       .. automethod:: simgrid.Barrier.__init__
2591       .. automethod:: simgrid.Barrier.wait
2592
2593    .. group-tab:: C
2594
2595       .. code-block:: C
2596
2597          #include <simgrid/barrier.hpp>
2598
2599       .. doxygentypedef:: sg_bar_t
2600
2601       .. doxygenfunction:: sg_barrier_init(unsigned int count)
2602       .. doxygenfunction:: sg_barrier_destroy(sg_bar_t bar)
2603       .. doxygenfunction:: sg_barrier_wait(sg_bar_t bar)
2604
2605
2606 .. _API_s4u_ConditionVariable:
2607
2608 ==========================
2609 ⁣  Condition variable
2610 ==========================
2611
2612 .. doxygenclass:: simgrid::s4u::ConditionVariable
2613
2614 Basic management
2615 ----------------
2616
2617    .. tabs::
2618
2619       .. group-tab:: C++
2620
2621          .. code-block:: C++
2622
2623             #include <simgrid/s4u/ConditionVariable.hpp>
2624
2625          .. doxygentypedef:: ConditionVariablePtr
2626
2627          .. doxygenfunction:: simgrid::s4u::ConditionVariable::create()
2628
2629       .. group-tab:: C
2630
2631          .. code-block:: C
2632
2633             #include <simgrid/cond.h>
2634
2635          .. doxygentypedef:: sg_cond_t
2636          .. doxygentypedef:: const_sg_cond_t
2637          .. doxygenfunction:: sg_cond_init
2638          .. doxygenfunction:: sg_cond_destroy
2639
2640 Waiting and notifying
2641 ---------------------
2642
2643    .. tabs::
2644
2645       .. group-tab:: C++
2646
2647          .. doxygenfunction:: simgrid::s4u::ConditionVariable::notify_all()
2648          .. doxygenfunction:: simgrid::s4u::ConditionVariable::notify_one()
2649          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(s4u::MutexPtr lock)
2650          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< s4u::Mutex > &lock)
2651          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock, P pred)
2652          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration)
2653          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration, P pred)
2654          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration)
2655          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred)
2656          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time)
2657          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred)
2658          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time)
2659          .. doxygenfunction:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time, P pred)
2660
2661       .. group-tab:: C
2662
2663          .. doxygenfunction:: sg_cond_notify_all
2664          .. doxygenfunction:: sg_cond_notify_one
2665          .. doxygenfunction:: sg_cond_wait
2666          .. doxygenfunction:: sg_cond_wait_for
2667
2668 .. _API_s4u_Semaphore:
2669
2670 ==================
2671 ⁣  Semaphore
2672 ==================
2673
2674 .. tabs::
2675
2676    .. group-tab:: C++
2677
2678       .. doxygenclass:: simgrid::s4u::Semaphore
2679
2680    .. group-tab:: Python
2681
2682       .. autoclass:: simgrid.Semaphore
2683
2684 Basic management
2685 ----------------
2686
2687    .. tabs::
2688
2689       .. group-tab:: C++
2690
2691          .. code-block:: C++
2692
2693             #include <simgrid/s4u/Semaphore.hpp>
2694
2695          .. doxygentypedef:: SemaphorePtr
2696          .. doxygenfunction:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity)
2697
2698       .. group-tab:: Python
2699
2700          .. code-block:: Python
2701
2702             from simgrid import Semaphore
2703             semaphore = Semaphore(1)
2704             # Automatically acquire the semaphore, and release it after leaving the scope.
2705             with semaphore:
2706                 # Do something with the shared resource
2707                 pass
2708
2709          .. automethod:: simgrid.Semaphore.__init__
2710
2711       .. group-tab:: C
2712
2713          .. code-block:: C
2714
2715             #include <simgrid/semaphore.h>
2716
2717          .. doxygentypedef:: sg_sem_t
2718          .. cpp:type:: const s4u_Semaphore* const_sg_sem_t
2719
2720             Pointer to a constant semaphore object.
2721
2722          .. doxygenfunction:: sg_sem_init(int initial_value)
2723          .. doxygenfunction:: sg_sem_destroy(const_sg_sem_t sem)
2724
2725 Locking
2726 -------
2727
2728    .. tabs::
2729
2730       .. group-tab:: C++
2731
2732          .. doxygenfunction:: simgrid::s4u::Semaphore::acquire()
2733          .. doxygenfunction:: simgrid::s4u::Semaphore::acquire_timeout(double timeout)
2734          .. doxygenfunction:: simgrid::s4u::Semaphore::get_capacity() const
2735          .. doxygenfunction:: simgrid::s4u::Semaphore::release()
2736          .. doxygenfunction:: simgrid::s4u::Semaphore::would_block() const
2737
2738       .. group-tab:: Python
2739
2740          .. automethod:: simgrid.Semaphore.acquire
2741          .. automethod:: simgrid.Semaphore.acquire_timeout
2742          .. autoattribute:: simgrid.Semaphore.capacity
2743          .. automethod:: simgrid.Semaphore.release
2744          .. autoattribute:: simgrid.Semaphore.would_block
2745
2746       .. group-tab:: C
2747
2748          .. doxygenfunction:: sg_sem_acquire(sg_sem_t sem)
2749          .. doxygenfunction:: sg_sem_acquire_timeout(sg_sem_t sem, double timeout)
2750          .. doxygenfunction:: sg_sem_get_capacity(const_sg_sem_t sem)
2751          .. doxygenfunction:: sg_sem_release(sg_sem_t sem)
2752          .. doxygenfunction:: sg_sem_would_block(const_sg_sem_t sem)
2753
2754 .. |hr| raw:: html
2755
2756    <hr />