X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/839e2fb8eb9378e4603161aef6caf6169d4bd788..39c935d6d5ee86d153f6f7e6a10d723ae7c57f6f:/examples/README.rst diff --git a/examples/README.rst b/examples/README.rst index 0420a65377..735ca8f79c 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -28,12 +28,12 @@ to simulate. 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 `, but you can + is a :ref:`better scientific habit `, but you can also create them directly from your code. .. tabs:: @@ -106,7 +106,7 @@ Starting and Stoping Actors 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:: @@ -147,7 +147,7 @@ Starting and Stoping Actors - **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:: @@ -289,33 +289,48 @@ Communications on the Network .. 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()`. @@ -326,15 +341,15 @@ Communications on the Network .. 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`. @@ -425,6 +440,13 @@ Executions on the CPU 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:: @@ -434,7 +456,7 @@ Executions on the CPU - **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:: @@ -629,14 +651,22 @@ Energy Simulation ================= - **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 @@ -648,14 +678,22 @@ Energy Simulation .. 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. @@ -679,13 +717,78 @@ options to see the task executions: - **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 ======================== @@ -875,14 +978,73 @@ Model-Related Examples 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