X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/4e62e76d104a17f0c9aaf9135ac605e9c8c87141..54aaefb7aa8fc6bfbdac47dfda2047989fb9b9f5:/examples/s4u/README.rst?ds=sidebyside diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst index e8bd8555df..c1ea3fe2e3 100644 --- a/examples/s4u/README.rst +++ b/examples/s4u/README.rst @@ -1,10 +1,5 @@ -.. S4U (Simgrid for you) is the next interface of SimGrid, expected to be released with SimGrid 4.0. +.. S4U (Simgrid for you) is the modern interface of SimGrid, which new project should use. .. -.. Even if it is not completely rock stable yet, it may well already fit -.. your needs. You are welcome to try it and report any interface -.. glitches that you see. Be however warned that the interface may change -.. until the final release. You will have to adapt your code on the way. -.. .. This file follows the ReStructured syntax to be included in the .. documentation, but it should remain readable directly. @@ -37,47 +32,165 @@ Starting and Stoping Actors --------------------------- - **Creating actors:** - Most actors are started from the deployment XML file, but there is other methods. - This example show them all. - `examples/python/actor-create/actor-create_d.xml `_ + Most actors are started from the deployment XML file, because this + is a :ref:`better scientific habbit `, but you can + also create them directly from your code. + + .. tabs:: + + .. group-tab:: C++ + + You create actors either: + + - Directly with :cpp:func:`simgrid::s4u::Actor::create` + - From XML with :cpp:func:`simgrid::s4u::Engine::register_actor` (if your actor is a class) + or :cpp:func:`simgrid::s4u::Engine::register_function` (if your actor is a function) + and then :cpp:func:`simgrid::s4u::Engine::load_deployment` + + .. toggle-header:: + :header: View examples/s4u/actor-create/s4u-actor-create.cpp + + `Download s4u-actor-create.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-create/s4u-actor-create.cpp + :language: cpp + + .. group-tab:: Python + + You create actors either: + + - Directly with :py:func:`simgrid.Actor.create()` + - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()` + + .. toggle-header:: + :header: View examples/python/actor-create/actor-create.py + + `Download actor-create.py `_ + + .. literalinclude:: ../../examples/python/actor-create/actor-create.py + + .. group-tab:: XML + + The following file is used in both C++ and Python. + + .. toggle-header:: + :header: View examples/python/actor-create/actor-create_d.xml + + `Download actor-create_d.xml `_ + + .. literalinclude:: ../../examples/python/actor-create/actor-create_d.xml + :language: xml + + - **React to the end of actors:** You can attach callbacks to the end of + actors. There is several ways of doing so, depending on whether you want to + attach your callback to a given actor and on how you define the end of a + given actor. User code probably want to react to the termination of an actor + while some plugins want to react to the destruction (memory collection) of + actors. + + .. tabs:: - - |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp `_ - - |py| `examples/python/actor-create/actor-create.py `_ + .. group-tab:: C++ - - **React to the end of actors:** - You can attach a callback to the end of actors. There is two ways - of doing so, depending of whether you want your callback to be - executed when a specific actor ends (with ```this_actor::on_exit()```) - or whether it should be executed when any actor ends (with - ```Actor::on_termination()```) or when it gets destroyed (with - ```Actor::on_destruction()```) + This example shows how to attach a callback to: - - |cpp| `examples/s4u/actor-exiting/s4u-actor-exiting.cpp `_ + - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()` + - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()` + - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()` + + .. toggle-header:: + :header: View examples/s4u/actor-exiting/s4u-actor-exiting.cpp + + `Download s4u-actor-exiting.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-exiting/s4u-actor-exiting.cpp + :language: cpp - **Kill actors:** Actors can forcefully stop other actors. - - |cpp| `examples/s4u/actor-kill/s4u-actor-kill.cpp `_ - :cpp:func:`void simgrid::s4u::Actor::kill(void)`, - :cpp:func:`void simgrid::s4u::Actor::kill_all()`, - :cpp:func:`simgrid::s4u::this_actor::exit`. - - |py| `examples/python/actor-kill/actor-kill.py `_ - :py:func:`simgrid.Actor.kill`, - :py:func:`simgrid.Actor.kill_all`, - :py:func:`simgrid.this_actor.exit`. + .. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`, :cpp:func:`simgrid::s4u::this_actor::exit`. + + .. toggle-header:: + :header: View examples/s4u/actor-kill/s4u-actor-kill.cpp + + `Download s4u-actor-kill.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-kill/s4u-actor-kill.cpp + :language: cpp + + .. group-tab:: Python + + See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`. + + .. toggle-header:: + :header: View examples/python/actor-kill/actor-kill.py + + `Download actor-kill.py `_ + + .. literalinclude:: ../../examples/python/actor-kill/actor-kill.py - **Controling the actor life cycle from the XML:** - You can specify a start time and a kill time in the deployment - file. - |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp `_ - |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml `_ + You can specify a start time and a kill time in the deployment file. + + .. tabs:: + + .. group-tab:: C++ + + This file is not really interesting: the important matter is in the XML file. + + .. toggle-header:: + :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp + + `Download s4u-actor-lifetime.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp + :language: cpp + + .. group-tab:: XML + + This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag. + + .. toggle-header:: + :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml + + `Download s4u-actor-lifetime_d.xml `_ + + .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml + :language: xml - **Daemonize actors:** Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular actor into a daemon that will be automatically killed once the simulation is over. - - |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp `_ - - |py| `examples/python/actor-daemon/actor-daemon.py `_ + .. tabs:: + + .. group-tab:: C++ + + See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`. + + .. toggle-header:: + :header: View examples/s4u/actor-daemon/s4u-actor-daemon.cpp + + `Download s4u-actor-daemon.cpp `_ + + .. literalinclude:: ../../examples/s4u/actor-daemon/s4u-actor-daemon.cpp + :language: cpp + + .. group-tab:: Python + + See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`. + + .. toggle-header:: + :header: View examples/python/actor-daemon/actor-daemon.py + + `Download actor-daemon.py `_ + + .. literalinclude:: ../../examples/python/actor-daemon/actor-daemon.py Inter-Actors Interactions -------------------------