.. 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.
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:
mailbox or a link. You can still destroy an host (but probably
shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
-C++ API Reference
-*****************
+.. 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:
=========
: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 generated with pybind11. It closely mimicks the C++
+The Python API is automatically generated with pybind11. It closely mimicks the C++
API, to which you should refer for more information.
==========
.. autoclass:: simgrid.Mailbox
:members:
+
+.. |hr| raw:: html
+
+ <hr />
