Actors: the Active Entities
===========================
-Starting and Stoping Actors
----------------------------
+Starting and Stopping Actors
+----------------------------
- **Creating actors:**
Most actors are started from the deployment XML file, because this
- is a :ref:`better scientific habbit <howto_science>`, but you can
+ is a :ref:`better scientific habit <howto_science>`, but you can
also create them directly from your code.
.. tabs::
See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
- - **Controling the actor life cycle from the XML:**
+ - **Controlling the actor life cycle from the XML:**
You can specify a start time and a kill time in the deployment file.
.. tabs::
- **Specify the stack size to use**
The stack size can be specified by default on the command line,
- globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config(std::string)`,
+ globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config`,
or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
.. tabs::
.. tabs::
- .. example-tab:: examples/s4u/async-wait/s4u-async-wait.cpp
+ .. example-tab:: examples/s4u/comm-wait/s4u-comm-wait.cpp
See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
- .. example-tab:: examples/python/async-wait/async-wait.py
+ .. example-tab:: examples/python/comm-wait/comm-wait.py
See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
- .. example-tab:: examples/c/async-wait/async-wait.c
+ .. example-tab:: examples/c/comm-wait/comm-wait.c
See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
+ - **Suspending communications:**
+ The ``suspend()`` and ``resume()`` functions allow to block the
+ progression of a given communication for a while and then unblock it.
+ ``is_suspended()`` can be used to retrieve whether the activity is
+ currently blocked or not.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/comm-suspend/s4u-comm-suspend.cpp
+
+ See also :cpp:func:`simgrid::s4u::Activity::suspend()`
+ :cpp:func:`simgrid::s4u::Activity::resume()` and
+ :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
+
+
- **Waiting for all communications in a set:**
The ``wait_all()`` function is useful when you want to block until
all activities in a given set have completed.
.. tabs::
- .. example-tab:: examples/s4u/async-waitall/s4u-async-waitall.cpp
+ .. example-tab:: examples/s4u/comm-waitall/s4u-comm-waitall.cpp
See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
- .. example-tab:: examples/python/async-waitall/async-waitall.py
+ .. example-tab:: examples/python/comm-waitall/comm-waitall.py
See also :py:func:`simgrid.Comm.wait_all()`.
- .. example-tab:: examples/c/async-waitall/async-waitall.c
+ .. example-tab:: examples/c/comm-waitall/comm-waitall.c
See also :cpp:func:`sg_comm_wait_all()`.
.. tabs::
- .. example-tab:: examples/s4u/async-waitany/s4u-async-waitany.cpp
+ .. example-tab:: examples/s4u/comm-waitany/s4u-comm-waitany.cpp
See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
- .. example-tab:: examples/python/async-waitany/async-waitany.py
+ .. example-tab:: examples/python/comm-waitany/comm-waitany.py
See also :py:func:`simgrid.Comm.wait_any()`.
- .. example-tab:: examples/c/async-waitany/async-waitany.c
+ .. example-tab:: examples/c/comm-waitany/comm-waitany.c
See also :cpp:func:`sg_comm_wait_any`.
computational kernels that span over several machines, such as a
PDGEM and the other ScaLAPACK routines. Note that this only works
with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
+
+ This example demonstrates several kind of parallel tasks: regular
+ ones, communication-only (without computation), computation-only
+ (without communication), synchronization-only (neither
+ communication nor computation). It also shows how to reconfigure a
+ task after its start, to change the amount of hosts it runs onto.
+ This allows to simulate malleable tasks.
.. tabs::
- **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::
=================
- **Describing the energy profiles in the platform:**
- This platform file contains the energy profile of each links and
- hosts, which is necessary to get energy consumption predictions.
- As usual, you should not trust our example, and you should strive
- to double-check that your instantiation matches your target platform.
+ The first platform file contains the energy profile of each links and
+ hosts for a wired network, which is necessary to get energy consumption
+ predictions. The second platform file is the equivalent for a wireless
+ network. As usual, you should not trust our example, and you should
+ strive to double-check that your instantiation matches your target
+ platform.
.. tabs::
- .. example-tab:: examples/platforms/energy_platform.xml
+ .. group-tab:: XML
+
+ .. showfile:: examples/platforms/energy_platform.xml
+ :language: xml
+
+ .. showfile:: examples/platforms/wifi_energy.xml
+ :language: xml
- **Consumption due to the CPU:**
This example shows how to retrieve the amount of energy consumed
.. example-tab:: examples/c/energy-exec/energy-exec.c
- - **Consumption due to the network:**
+ - **Consumption due to the wired network:**
This example shows how to retrieve and display the energy consumed
- by the network during communications.
+ by the wired network during communications.
.. tabs::
.. example-tab:: examples/s4u/energy-link/s4u-energy-link.cpp
+ - **Consumption due to the wireless network:**
+ This example shows how to retrieve and display the energy consumed
+ by the wireless network during communications.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/energy-wifi/s4u-energy-wifi.cpp
+
- **Modeling the shutdown and boot of hosts:**
Simple example of model of model for the energy consumption during
the host boot and shutdown periods.
- **Platform Tracing:**
This program is a toy example just loading the platform, so that
- you can play with the platform visualization. Recommanded options:
+ you can play with the platform visualization. Recommended options:
``--cfg=tracing:yes --cfg=tracing/categorized:yes``
.. tabs::
.. example-tab:: examples/s4u/trace-platform/s4u-trace-platform.cpp
+ - **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``
+
+ .. tabs::
+
+ .. 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/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
========================
with the ns-3 bindings of SimGrid and the tesh file to see how to actually
start a simulation in these settings.
- .. example-tab:: examples/s4u/network-ns3/s4u-network-ns3.cpp
+ .. tabs::
+
+ .. example-tab:: examples/s4u/network-ns3/s4u-network-ns3.cpp
- .. group-tab:: XML
+ .. group-tab:: XML
**Platform files:**
.. showfile:: examples/platforms/small_platform_one_link_routes.xml
:language: xml
+
+ - **wifi links**
+
+ This demonstrates how to declare a wifi link in your platform and
+ how to use it in your simulation. The basics is to have a link
+ which sharing policy is set to `WIFI`. Such links can have more
+ than one bandwidth value (separated by commas), corresponding to
+ the several SNR level of your wifi link.
+
+ In this case, SimGrid automatically switches to validated
+ performance models of wifi networks, where the time is shared
+ between users instead of the bandwidth for wired links (the
+ corresponding publication is currently being written).
+
+ If your wifi link provides more than one SNR level, you can switch
+ the level of a given host using
+ :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
+ the first level is used.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/network-wifi/s4u-network-wifi.cpp
+
+ .. group-tab:: XML
+
+ **Platform files:**
+
+ .. 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
