.. raw:: html
- <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
+ <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
<script>
window.onload=function() { // Wait for the SVG to be loaded before changing it
- var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
- elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
+ var elem=document.querySelector("#TOC").contentDocument.getElementById("ActorBox")
+ 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";
}
</script>
<br/>
deprecation warnings for 4 releases (one year) before the removal of
the old symbols.
If you want an API that will never ever evolve in the future, you
-should use the deprecated MSG API instead.
+should use the :ref:`deprecated MSG API <MSG_doc>` instead.
Main Concepts
*************
:ref:`communication <API_s4u_Comm>`, :ref:`disk usage <API_s4u_Io>`,
and other |API_s4u_Activities|_, so that they get reflected within the
simulator. These activities take place on resources such as |API_s4u_Hosts|_,
-|API_s4u_Links|_ and |API_s4u_Storages|_. SimGrid predicts the time taken by each
+|API_s4u_Links|_ and |API_s4u_Disks|_. SimGrid predicts the time taken by each
activity and orchestrates the actors accordingly, waiting for the
completion of these activities.
- **Global Classes**
- - :ref:`class
s4u::Actor <API_s4u_Actor>`:
+ - :ref:`class Actor <API_s4u_Actor>`:
Active entities executing your application.
- - :ref:`class
s4u::Engine <API_s4u_Engine>`
+ - :ref:`class Engine <API_s4u_Engine>`
Simulation engine (singleton).
- - :ref:`class
s4u::Mailbox <API_s4u_Mailbox>`
+ - :ref:`class Mailbox <API_s4u_Mailbox>`
Communication rendez-vous.
- **Platform Elements**
- - :ref:`class s4u::Host <API_s4u_Host>`:
+ - :ref:`class Disk <API_s4u_Disk>`
+ Resource on which actors can write and read data.
+ - :ref:`class Host <API_s4u_Host>`:
Actor location, providing computational power.
- - :ref:`class
s4u::Link <API_s4u_Link>`
+ - :ref:`class Link <API_s4u_Link>`
Interconnecting hosts.
- - :ref:`class
s4u::NetZone <API_s4u_NetZone>`:
+ - :ref:`class NetZone <API_s4u_NetZone>`:
Sub-region of the platform, containing resources (Hosts, Links, etc).
- - :ref:`class s4u::Storage <API_s4u_Storage>`
- Resource on which actors can write and read data.
- - :ref:`class s4u::VirtualMachine <API_s4u_VirtualMachine>`:
+ - :ref:`class VirtualMachine <API_s4u_VirtualMachine>`:
Execution containers that can be moved between Hosts.
-- **Activities** (:ref:`class
s4u::Activity <API_s4u_Activity>`):
+- **Activities** (:ref:`class Activity <API_s4u_Activity>`):
The things that actors can do on resources
- - :ref:`class
s4u::Comm <API_s4u_Comm>`
+ - :ref:`class Comm <API_s4u_Comm>`
Communication activity, started on Mailboxes and consuming links.
- - :ref:`class
s4u::Exec <API_s4u_Exec>`
+ - :ref:`class Exec <API_s4u_Exec>`
Computation activity, started on Host and consuming CPU resources.
- - :ref:`class
s4u::Io <API_s4u_Io>`
- I/O activity, started on and consumming Storages.
+ - :ref:`class Io <API_s4u_Io>`
+ I/O activity, started on and consumming disks.
- **Synchronization Mechanisms**: Classical IPC that actors can use
- - :ref:`class
s4u::Barrier <API_s4u_Barrier>`
- - :ref:`class
s4u::ConditionVariable <API_s4u_ConditionVariable>`
- - :ref:`class
s4u::Mutex <API_s4u_Mutex>`
- - :ref:`class
s4u::Semaphore <API_s4u_Semaphore>`
+ - :ref:`class Barrier <API_s4u_Barrier>`
+ - :ref:`class ConditionVariable <API_s4u_ConditionVariable>`
+ - :ref:`class Mutex <API_s4u_Mutex>`
+ - :ref:`class Semaphore <API_s4u_Semaphore>`
.. |API_s4u_Actors| replace:: **Actors**
-.. _API_s4u_Actors: #s4u-actor
+.. _API_s4u_Actors: #api-s4u-actor
.. |API_s4u_Activities| replace:: **Activities**
-.. _API_s4u_Activities: #s4u-activity
+.. _API_s4u_Activities: #api-s4u-activity
.. |API_s4u_Hosts| replace:: **Hosts**
-.. _API_s4u_Hosts: #s4u-host
+.. _API_s4u_Hosts: #api-s4u-host
.. |API_s4u_Links| replace:: **Links**
-.. _API_s4u_Links: #s4u-link
+.. _API_s4u_Links: #api-s4u-link
-.. |API_s4u_Storages| replace:: **Storages**
-.. _API_s4u_Storages: #s4u-storage
+.. |API_s4u_Disks| replace:: **Disks**
+.. _API_s4u_Disks: #api-s4u-disk
.. |API_s4u_VirtualMachine| replace:: **VirtualMachines**
.. |API_s4u_Mutex| replace:: **Mutex**
-.. THE EXAMPLES
-
-.. include:: ../../examples/s4u/README.rst
+.. _s4u_Activities:
Activities
**********
Activities represent the actions that consume a resource, such as a
-:ref:`s4u::Comm <API_s4u_Comm>` that consumes the *transmiting power* of
-:ref:`s4u::Link <API_s4u_Link>` resources.
+:ref:`Comm <API_s4u_Comm>` that consumes the *transmitting power* of
+:ref:`Link <API_s4u_Link>` resources, or an :ref:`Exec <API_s4u_Exec>`
+that consumes the *computing power* of :ref:`Host <API_s4u_Host>` resources.
+See also the :ref:`full API <API_s4u_Activity>` below.
=======================
Asynchronous Activities
wait_for and wait_until are currently not implemented for Exec and Io activities.
-Every kind of activities can be asynchronous:
+Every kind of activity can be asynchronous:
- :ref:`s4u::CommPtr <API_s4u_Comm>` are created with
:cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
:cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
- :ref:`s4u::IoPtr <API_s4u_Io>` are created with
- :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
- :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.
+ :cpp:func:`s4u::Disk::read_async() <simgrid::s4u::Disk::read_async>` and
+ :cpp:func:`s4u::Disk::write_async() <simgrid::s4u::Disk::write_async>`.
- :ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
:cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
- In the future, it will become possible to have asynchronous IPC
to be exchanged only when both the sender and the receiver are
announced (it waits until both :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
and :cpp:func:`get() <simgrid::s4u::Mailbox::get()>` are posted).
-In TCP, since you establish connexions beforehand, the data starts to
+In TCP, since you establish connections beforehand, the data starts to
flow as soon as the sender posts it, even if the receiver did not post
its :cpp:func:`recv() <simgrid::s4u::Mailbox::recv()>` yet.
For sake of simplicity, we use `RAII
<https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
-everywhere in S4U. This is an idiom where resources are automatically
+for many classes in S4U. This is an idiom where resources are automatically
managed through the context. Provided that you never manipulate
objects of type Foo directly but always FooPtr references (which are
defined as `boost::intrusive_ptr
<http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
-<Foo>), you will never have to explicitely release the resource that
+<Foo>), you will never have to explicitly release the resource that
you use nor to free the memory of unused objects.
-
Here is a little example:
.. code-block:: cpp
} // The mutex gets automatically freed because the only existing reference gets out of scope
+Note that Mailboxes, Hosts and Links are not handled thought smart
+pointers (yet?). This means that it is currently impossible to destroy a
+mailbox or a link. You can still destroy an host (but probably
+shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
+
+.. THE EXAMPLES
+
+.. include:: ../../examples/README.rst
+
API Reference
*************
.. _API_s4u_this_actor:
-=========================
-namespace s4u::this_actor
-=========================
+==================================
+Interacting with the current actor
+==================================
+
+Static methods working on the current actor (see :ref:`API_s4u_Actor`).
.. doxygennamespace:: simgrid::s4u::this_actor
+
.. _API_s4u_Activity:
-=============
-s4u::Activity
-=============
+==============
+class Activity
+==============
+
+.. autodoxyclass:: simgrid::s4u::Activity
+
+ **Known subclasses:**
+ :ref:`Communications <API_s4u_Comm>` (started on Mailboxes and consuming links),
+ :ref:`Executions <API_s4u_Exec>` (started on Host and consuming CPU resources)
+ :ref:`I/O <API_s4u_Io>` (started on and consumming disks).
+ See also the :ref:`section on activities <s4u_Activities>` above.
+
+Querying info about activities
+------------------------------
+
+ .. autodoxymethod:: simgrid::s4u::Activity::get_remaining()
+ .. autodoxymethod:: simgrid::s4u::Activity::get_state()
+ .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains)
+ .. autodoxymethod:: simgrid::s4u::Activity::get_impl
+
+Activities lifecycle
+--------------------
+
+ .. autodoxymethod:: simgrid::s4u::Activity::cancel
+ .. autodoxymethod:: simgrid::s4u::Activity::start
+ .. autodoxymethod:: simgrid::s4u::Activity::test
+ .. autodoxymethod:: simgrid::s4u::Activity::wait
+ .. autodoxymethod:: simgrid::s4u::Activity::wait_for
+ .. autodoxymethod:: simgrid::s4u::Activity::wait_until(double time_limit)
-.. doxygenclass:: simgrid::s4u::Activity
- :members:
- :protected-members:
- :undoc-members:
.. _API_s4u_Actor:
-==========
-s4u::Actor
-==========
+===========
+class Actor
+===========
.. doxygentypedef:: ActorPtr
.. doxygentypedef:: aid_t
-.. doxygenclass:: simgrid::s4u::Actor
- :members:
- :protected-members:
- :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Actor
+
+Creating actors
+---------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code)
+ .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code)
+ .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args)
+ .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector< std::string > args)
+
+ .. autodoxymethod:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host)
+ .. autodoxymethod:: simgrid::s4u::Actor::start(const std::function< void()> &code)
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Actor.create
+
+Searching specific actors
+-------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::by_pid(aid_t pid)
+ .. autodoxymethod:: simgrid::s4u::Actor::self()
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Actor.by_pid
+ .. automethod:: simgrid.Actor.self
+
+Querying info about actors
+--------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::get_cname
+ .. autodoxymethod:: simgrid::s4u::Actor::get_name
+ .. autodoxymethod:: simgrid::s4u::Actor::get_pid
+ .. autodoxymethod:: simgrid::s4u::Actor::get_ppid
+ .. autodoxymethod:: simgrid::s4u::Actor::get_properties() const
+ .. autodoxymethod:: simgrid::s4u::Actor::get_property(const std::string &key) const
+ .. autodoxymethod:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value)
+
+ .. autodoxymethod:: simgrid::s4u::Actor::get_host
+ .. autodoxymethod:: simgrid::s4u::Actor::migrate
+
+ .. autodoxymethod:: simgrid::s4u::Actor::get_refcount()
+ .. autodoxymethod:: simgrid::s4u::Actor::get_impl
+
+ .. group-tab:: Python
+
+ .. autoattribute:: simgrid.Actor.name
+ .. autoattribute:: simgrid.Actor.host
+ .. autoattribute:: simgrid.Actor.pid
+ .. autoattribute:: simgrid.Actor.ppid
+
+ .. automethod:: simgrid.Actor.migrate
+
+Suspending and resuming actors
+------------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::suspend()
+ .. autodoxymethod:: simgrid::s4u::Actor::resume()
+ .. autodoxymethod:: simgrid::s4u::Actor::is_suspended()
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Actor.resume
+ .. automethod:: simgrid.Actor.suspend
+ .. automethod:: simgrid.Actor.is_suspended
+
+Killing actors
+--------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::kill()
+ .. autodoxymethod:: simgrid::s4u::Actor::kill_all()
+ .. autodoxymethod:: simgrid::s4u::Actor::set_kill_time(double time)
+ .. autodoxymethod:: simgrid::s4u::Actor::get_kill_time()
+
+ .. autodoxymethod:: simgrid::s4u::Actor::restart()
+ .. autodoxymethod:: simgrid::s4u::Actor::daemonize()
+ .. autodoxymethod:: simgrid::s4u::Actor::is_daemon
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Actor.kill
+ .. automethod:: simgrid.Actor.kill_all
+
+ .. automethod:: simgrid.Actor.daemonize
+ .. automethod:: simgrid.Actor.is_daemon
+
+Reacting to the end of actors
+-----------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Actor::on_exit
+ .. autodoxymethod:: simgrid::s4u::Actor::join()
+ .. autodoxymethod:: simgrid::s4u::Actor::join(double timeout)
+ .. autodoxymethod:: simgrid::s4u::Actor::set_auto_restart(bool autorestart)
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Actor.join
+
+Signals
+-------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxyvar:: simgrid::s4u::Actor::on_creation
+ .. autodoxyvar:: simgrid::s4u::Actor::on_suspend
+ .. autodoxyvar:: simgrid::s4u::Actor::on_resume
+ .. autodoxyvar:: simgrid::s4u::Actor::on_sleep
+ .. autodoxyvar:: simgrid::s4u::Actor::on_wake_up
+ .. autodoxyvar:: simgrid::s4u::Actor::on_migration_start
+ .. autodoxyvar:: simgrid::s4u::Actor::on_migration_end
+ .. autodoxyvar:: simgrid::s4u::Actor::on_termination
+ .. autodoxyvar:: simgrid::s4u::Actor::on_destruction
.. _API_s4u_Barrier:
-============
-s4u::Barrier
-============
+=============
+class Barrier
+=============
.. doxygentypedef:: BarrierPtr
-.. doxygenclass:: simgrid::s4u::Barrier
- :members:
- :protected-members:
- :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Barrier
+
+ .. tabs::
+
+ .. group-tab:: C++
+
+ .. autodoxymethod:: simgrid::s4u::Barrier::Barrier(unsigned int count)
+ .. autodoxymethod:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
+ .. autodoxymethod:: simgrid::s4u::Barrier::wait()
+
.. _API_s4u_Comm:
:protected-members:
:undoc-members:
+.. _API_s4u_Disk:
+
+============
+s4u::Disk
+============
+
+.. doxygenclass:: simgrid::s4u::Disk
+ :members:
+ :protected-members:
+ :undoc-members:
+
.. _API_s4u_Engine:
===========
:protected-members:
:undoc-members:
+.. _API_s4u_ExecSeq:
+
+============
+s4u::ExecSeq
+============
+
+.. doxygentypedef:: ExecSeqPtr
+
+.. doxygenclass:: simgrid::s4u::ExecSeq
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_ExecPar:
+
+============
+s4u::ExecPar
+============
+
+.. doxygentypedef:: ExecParPtr
+
+.. doxygenclass:: simgrid::s4u::ExecPar
+ :members:
+ :protected-members:
+ :undoc-members:
+
.. _API_s4u_Host:
=========
Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
-.. doxygentypedef:: MailboxPtr
-
.. doxygenclass:: simgrid::s4u::Mailbox
:members:
:protected-members:
:protected-members:
:undoc-members:
-.. _API_s4u_Storage:
-
-============
-s4u::Storage
-============
-
-.. doxygenclass:: simgrid::s4u::Storage
- :members:
- :protected-members:
- :undoc-members:
-
.. _API_s4u_VirtualMachine:
===================
:protected-members:
:undoc-members:
+C API Reference
+***************
+
+==============
+Main functions
+==============
+
+.. doxygenfunction:: simgrid_init
+.. doxygenfunction:: simgrid_get_clock
+.. doxygenfunction:: simgrid_load_deployment
+.. doxygenfunction:: simgrid_load_platform
+.. doxygenfunction:: simgrid_register_default
+.. doxygenfunction:: simgrid_register_function
+.. doxygenfunction:: simgrid_run
+
+==================
+Condition Variable
+==================
+
+See also the :ref:`C++ API <API_s4u_ConditionVariable>`.
+
+.. doxygenfunction:: sg_cond_init
+.. doxygenfunction:: sg_cond_notify_all
+.. doxygenfunction:: sg_cond_notify_one
+.. doxygenfunction:: sg_cond_wait
+.. doxygenfunction:: sg_cond_wait_for
+
+Python API Reference
+********************
+
+The Python API is automatically generated with pybind11. It closely mimicks the C++
+API, to which you should refer for more information.
+
+==========
+this_actor
+==========
+
+.. automodule:: simgrid.this_actor
+ :members:
+
+===========
+Class Actor
+===========
+
+.. autoclass:: simgrid.Actor
+ :members:
+
+==========
+Class Comm
+==========
+
+.. autoclass:: simgrid.Comm
+ :members:
+
+============
+Class Engine
+============
+
+.. autoclass:: simgrid.Engine
+ :members:
+
+==========
+Class Exec
+==========
+
+.. autoclass:: simgrid.Exec
+ :members:
+
+==========
+Class Host
+==========
+
+.. autoclass:: simgrid.Host
+ :members:
+
+=============
+Class Mailbox
+=============
+
+.. autoclass:: simgrid.Mailbox
+ :members:
+
+.. |hr| raw:: html
+
+ <hr />
