docs/source/app_s4u.rst

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