This example shows how to attach a callback to:
- - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()`
+ - the end of a specific actor: :cpp:func:`simgrid::s4u::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()`
.. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
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`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.
+ :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`.
.. example-tab:: examples/python/actor-kill/actor-kill.py
Communications on the Network
-----------------------------
+ - **Basic communications:**
+ This simple example just sends one message back and forth.
+ The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to
+ the simulators (as detailed in Section :ref:`options`).
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/comm-pingpong/s4u-comm-pingpong.cpp
+
+ .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
+
+
- **Basic asynchronous communications:**
Illustrates how to have non-blocking communications, that are
communications running in the background leaving the process free
See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
+ - **Waiting communications with timeouts:**
+ This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/comm-waituntil/s4u-comm-waituntil.cpp
+
+ See also :cpp:func:`simgrid::s4u::Mailbox::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
+
- **Suspending communications:**
The ``suspend()`` and ``resume()`` functions allow to block the
progression of a given communication for a while and then unblock it.
- **Using Pstates on a host:**
This example shows how define a set of pstates in the XML. The current pstate
- of an host can then be accessed and changed from the program.
+ of a host can then be accessed and changed from the program.
.. tabs::
.. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
- - **Condition variable:**
+ - **Condition variable: basic usage**
Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
.. tabs::
.. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
+ - **Condition variable: timeouts**
+ Shows how to specify timeouts when blocking on condition variables.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
+
- **Mutex:**
Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
.. example-tab:: examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp
+ .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
+
=============================
Interacting with the Platform
=============================
.. example-tab:: examples/s4u/trace-platform/s4u-trace-platform.cpp
-========================
-Larger SimGrid Examplars
-========================
+ - **Setting Categories**
+ This example declares several tracing categories to that are used to
+ classify its tasks. When the program is executed, the tracing mechanism
+ registers the resource utilization of hosts and links according to these
+ categories. Recommended options:
+ ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
-This section contains application examples that are somewhat larger
-than the previous examples.
+ .. tabs::
- - **Ping Pong:**
- This simple example just sends one message back and forth.
- The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to
- the simulators (as detailed in Section :ref:`options`).
+ .. example-tab:: examples/s4u/trace-categories/s4u-trace-categories.cpp
+
+ - **Master Workers tracing**
+ This is an augmented version of our basic master/worker example using
+ several tracing features. It traces resource usage, sorted out in several
+ categories; Trace marks and user variables are also used. Recommended
+ options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/trace-masterworkers/s4u-trace-masterworkers.cpp
+
+ - **Process migration tracing**
+ This version is enhanced so that the process migrations can be displayed
+ as arrows in a Gantt-chart visualization. Recommended options to that
+ extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/trace-process-migration/s4u-trace-process-migration.cpp
+
+..
+ TODO: These tracing examples should be integrated in the examples to not
+ duplicate the C++ files. A full command line to see the result in the right
+ tool (vite/FrameSoc) should be given along with some screenshots.
+
+Tracing user variables
+----------------------
+
+You can also attach your own variables to any resource described in the platform
+file. The following examples illustrate this feature. They have to be run with
+the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
+
+ - **Attaching variables to Hosts**
.. tabs::
- .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
+ .. example-tab:: examples/s4u/trace-host-user-variables/s4u-trace-host-user-variables.cpp
+
+ - **Attaching variables to Links**
+ The tricky part is that you have to know the name of the link you want to
+ enhance with a variable.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/trace-link-user-variables/s4u-trace-link-user-variables.cpp
+
+ - **Attaching variables to network Routes**
+ It is often easier to update a given variable for all links of a given
+ network path (identified by its source and destination hosts) instead of
+ knowing the name of each specific link.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/trace-route-user-variables/s4u-trace-route-user-variables.cpp
+
+========================
+Larger SimGrid Examplars
+========================
- .. example-tab:: examples/c/app-pingpong/app-pingpong.c
+This section contains application examples that are somewhat larger
+than the previous examples.
- **Token ring:**
Shows how to implement a classical communication pattern, where a
.. showfile:: examples/platforms/wifi.xml
:language: xml
+===============
+Plugin Examples
+===============
+
+It is possible to extend SimGrid without modifying its internals by
+attaching code to the existing signals and by adding extra data to the
+simulation objects through extensions. How to do that is not exactly
+documented yet, and you should look for examples in the src/plugins
+directory.
+
+This section documents how the existing plugins can be used. Remember
+that you are very welcome to modify the plugins to fit your needs. It
+should be much easier than modifying the SimGrid kernel.
+
+ - **Monitoring the host load**
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/plugin-host-load/s4u-plugin-host-load.cpp
+
+ .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
+
+ - **Monitoring the link load**
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/plugin-link-load/s4u-plugin-link-load.cpp
+
=======================
Model-Checking Examples
=======================