Release v3.26

[simgrid.git] / examples / README.rst

diff --git a/examples/README.rst b/examples/README.rst
index bf2135b2717c9b8a1b46f56f54a0f20a39ae8df0..735ca8f79cb05092cc4be21fa546a40b9f083533 100644 (file)
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -4,8 +4,8 @@
 .. documentation, but it should remain readable directly.
 
 
 .. documentation, but it should remain readable directly.
 
 

-S4U Examples
-************
+Examples
+********

 
 SimGrid comes with an extensive set of examples, documented on this
 page. Most of them only demonstrate one single feature, with some
 
 SimGrid comes with an extensive set of examples, documented on this
 page. Most of them only demonstrate one single feature, with some


@@ -22,18 +22,18 @@ A good way to bootstrap your own project is to copy and combine some
 of the provided examples to constitute the skeleton of what you plan
 to simulate.
 
 of the provided examples to constitute the skeleton of what you plan
 to simulate.
 

+.. _s4u_ex_actors:
+

 ===========================
 Actors: the Active Entities
 ===========================
 
 ===========================
 Actors: the Active Entities
 ===========================
 

-.. _s4u_ex_actors:
-
-Starting and Stoping Actors
----------------------------
+Starting and Stopping Actors
+----------------------------

 
   - **Creating actors:**
     Most actors are started from the deployment XML file, because this
 
   - **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::
     also create them directly from your code.
 
     .. tabs::


@@ -54,6 +54,13 @@ Starting and Stoping Actors
           - Directly with :py:func:`simgrid.Actor.create()`
           - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
              
           - Directly with :py:func:`simgrid.Actor.create()`
           - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
              

+       .. example-tab:: examples/c/actor-create/actor-create.c
+       
+          You create actors either:
+            
+          - Directly with :cpp:func:`sg_actor_create()` followed by :cpp:func:`sg_actor_start`.
+          - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
+             

        .. example-tab:: examples/python/actor-create/actor-create_d.xml
        
           The following file is used in both C++ and Python.
        .. example-tab:: examples/python/actor-create/actor-create_d.xml
        
           The following file is used in both C++ and Python.


@@ -75,21 +82,31 @@ Starting and Stoping Actors
           - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
           - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
 
           - 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/c/actor-exiting/actor-exiting.c
+
+          This example shows how to attach a callback to the end of a specific actor with 
+          :cpp:func:`sg_actor_on_exit()`.
+

   - **Kill actors:**
     Actors can forcefully stop other actors.
   - **Kill actors:**
     Actors can forcefully stop other actors.

-    
+

     .. tabs::
     .. tabs::

-    
+

        .. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
        .. 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()`,
           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::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.

 
        .. example-tab:: examples/python/actor-kill/actor-kill.py
 
 
        .. example-tab:: examples/python/actor-kill/actor-kill.py
 

-          See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`.
+          See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
+          :py:func:`simgrid.this_actor.on_exit`.
+
+       .. example-tab:: examples/c/actor-kill/actor-kill.c

 
 

-  - **Controling the actor life cycle from the XML:**
+          See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
+
+  - **Controlling the actor life cycle from the XML:**

     You can specify a start time and a kill time in the deployment file.
 
     .. tabs::
     You can specify a start time and a kill time in the deployment file.
 
     .. tabs::


@@ -102,6 +119,14 @@ Starting and Stoping Actors
 
           This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
 
 
           This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
 

+       .. example-tab:: examples/python/actor-lifetime/actor-lifetime.py
+
+          This file is not really interesting: the important matter is in the XML file.
+
+      .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
+
+          This file is not really interesting: the important matter is in the XML file.
+

   - **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.
   - **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.


@@ -116,6 +141,21 @@ Starting and Stoping Actors
 
           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 
 
           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 

+       .. example-tab:: examples/c/actor-daemon/actor-daemon.c
+
+          See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
+
+  - **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`,
+    or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
+    
+    .. tabs::
+
+       .. example-tab:: examples/s4u/actor-stacksize/s4u-actor-stacksize.cpp
+
+       .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
+

 Inter-Actors Interactions
 -------------------------
 
 Inter-Actors Interactions
 -------------------------
 


@@ -131,27 +171,36 @@ synchronization objects <s4u_ex_IPC>`.
        .. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp
 
           See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
        .. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp
 
           See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,

-          :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()` and
+          :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and

           :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 
        .. example-tab:: examples/python/actor-suspend/actor-suspend.py
 
           See also :py:func:`simgrid.this_actor.suspend()`,
           :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 
        .. example-tab:: examples/python/actor-suspend/actor-suspend.py
 
           See also :py:func:`simgrid.this_actor.suspend()`,

-          :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()` and
+          :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and

           :py:func:`simgrid.Actor.is_suspended()`.
 
           :py:func:`simgrid.Actor.is_suspended()`.
 

+       .. example-tab:: examples/c/actor-suspend/actor-suspend.c
+
+          See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and 
+          :cpp:func:`sg_actor_is_suspended()`.
+

   - **Migrating Actors:**
   - **Migrating Actors:**

-    Actors can move or be moved from a host to another very easily.
+    Actors can move or be moved from a host to another very easily. It amount to setting them on a new host.

 
     .. tabs::
 
        .. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp
 
 
     .. tabs::
 
        .. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp
 

-          See also :cpp:func:`simgrid::s4u::this_actor::migrate()` and :cpp:func:`simgrid::s4u::Actor::migrate()`.
+          See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.

 
        .. example-tab:: examples/python/actor-migrate/actor-migrate.py
 
 
        .. example-tab:: examples/python/actor-migrate/actor-migrate.py
 

-          See also :py:func:`simgrid.this_actor.migrate()` and :py:func:`simgrid.Actor.migrate()`.
+          See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
+
+       .. example-tab:: examples/c/actor-migrate/actor-migrate.c
+
+          See also :cpp:func:`sg_actor_set_host()`.

 
   - **Waiting for the termination of an actor:** (joining on it)
     You can block the current actor until the end of another actor.
 
   - **Waiting for the termination of an actor:** (joining on it)
     You can block the current actor until the end of another actor.


@@ -166,6 +215,10 @@ synchronization objects <s4u_ex_IPC>`.
 
           See also :py:func:`simgrid.Actor.join()`.
 
 
           See also :py:func:`simgrid.Actor.join()`.
 

+       .. example-tab:: examples/c/actor-join/actor-join.c
+
+          See also :cpp:func:`sg_actor_join`.
+

   - **Yielding to other actors**.
     The ```yield()``` function interrupts the execution of the current
     actor, leaving a chance to the other actors that are ready to run
   - **Yielding to other actors**.
     The ```yield()``` function interrupts the execution of the current
     actor, leaving a chance to the other actors that are ready to run


@@ -181,6 +234,10 @@ synchronization objects <s4u_ex_IPC>`.
 
           See also :py:func:`simgrid.this_actor.yield_()`.
 
 
           See also :py:func:`simgrid.this_actor.yield_()`.
 

+       .. example-tab:: examples/c/actor-yield/actor-yield.c
+
+          See also :cpp:func:`sg_actor_yield()`.
+

 Traces Replay as a Workload
 ---------------------------
 
 Traces Replay as a Workload
 ---------------------------
 


@@ -232,28 +289,51 @@ Communications on the Network
 
    .. 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()`.
 
 
          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()`.
 
 
          See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
 

+      .. 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::
 
  - **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()`.
 
 
          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()`.
 
 
          See also :py:func:`simgrid.Comm.wait_all()`.
 

+      .. example-tab:: examples/c/comm-waitall/comm-waitall.c
+
+         See also :cpp:func:`sg_comm_wait_all()`.
+

  - **Waiting for the first completed communication in a set:**
    The ``wait_any()`` function is useful
    when you want to block until one activity of the set completes, no
  - **Waiting for the first completed communication in a set:**
    The ``wait_any()`` function is useful
    when you want to block until one activity of the set completes, no


@@ -261,13 +341,17 @@ Communications on the Network
    
    .. tabs::
 
    
    .. 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()`.
 
 
          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()`.
 
          See also :py:func:`simgrid.Comm.wait_any()`.

+        
+      .. example-tab:: examples/c/comm-waitany/comm-waitany.c
+
+         See also :cpp:func:`sg_comm_wait_any`.

      
 .. _s4u_ex_execution:
 
      
 .. _s4u_ex_execution:
 


@@ -292,6 +376,11 @@ Executions on the CPU
 
           See also :py:func:`simgrid.this_actor.execute()`.
 
 
           See also :py:func:`simgrid.this_actor.execute()`.
 

+       .. example-tab:: examples/c/exec-basic/exec-basic.c
+
+          See also :cpp:func:`void sg_actor_execute(double)`
+          and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
+

   - **Asynchronous execution:**
     You can start asynchronous executions, just like you would fire
     background threads.
   - **Asynchronous execution:**
     You can start asynchronous executions, just like you would fire
     background threads.


@@ -317,7 +406,17 @@ Executions on the CPU
           :py:func:`simgrid.Exec.get_remaining_ratio()`,
           :py:func:`simgrid.this_actor.exec_async()` and
           :py:func:`simgrid.Activity.cancel()`.
           :py:func:`simgrid.Exec.get_remaining_ratio()`,
           :py:func:`simgrid.this_actor.exec_async()` and
           :py:func:`simgrid.Activity.cancel()`.

-
+ 
+       .. example-tab:: examples/c/exec-async/exec-async.c
+
+          See also :cpp:func:`sg_actor_exec_init()`,
+          :cpp:func:`sg_exec_start()`,
+          :cpp:func:`sg_exec_wait()`,
+          :cpp:func:`sg_exec_get_remaining()`,
+          :cpp:func:`sg_exec_get_remaining_ratio()`,
+          :cpp:func:`sg_actor_exec_async()` and
+          :cpp:func:`sg_exec_cancel()`,
+          

   - **Remote execution:**
     You can start executions on remote hosts, or even change the host
     on which they occur during their execution.
   - **Remote execution:**
     You can start executions on remote hosts, or even change the host
     on which they occur during their execution.


@@ -332,11 +431,22 @@ Executions on the CPU
 
           See also :py:func:`simgrid.Exec.set_host()`.
 
 
           See also :py:func:`simgrid.Exec.set_host()`.
 

+       .. example-tab:: examples/c/exec-remote/exec-remote.c
+
+          See also :cpp:func:`sg_exec_set_host()`.
+

   - **Parallel executions:**
     These objects are convenient abstractions of parallel
     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``).
   - **Parallel executions:**
     These objects are convenient abstractions of parallel
     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::
 
 
     .. tabs::
 


@@ -346,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
 
   - **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::
 
 
     .. tabs::
 


@@ -354,12 +464,18 @@ Executions on the CPU
 
           See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 
 
           See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 

+       .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
+
+          See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
+

        .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 
           See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 
        .. example-tab:: examples/platforms/energy_platform.xml
 
        .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 
           See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 
        .. example-tab:: examples/platforms/energy_platform.xml
 

+.. _s4u_ex_disk_io:
+

 I/O on Disks and Files
 ----------------------
 
 I/O on Disks and Files
 ----------------------
 


@@ -375,6 +491,8 @@ write actions on the disk resources.
 
        .. example-tab:: examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp
 
 
        .. example-tab:: examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp
 

+       .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
+

        .. example-tab:: examples/platforms/hosts_with_disks.xml
 
           This shows how to declare disks in XML.
        .. example-tab:: examples/platforms/hosts_with_disks.xml
 
           This shows how to declare disks in XML.


@@ -400,27 +518,36 @@ result in short reads and short write, as in reality.
 
        .. example-tab:: examples/s4u/io-file-remote/s4u-io-file-remote.cpp
 
 
        .. example-tab:: examples/s4u/io-file-remote/s4u-io-file-remote.cpp
 

+       .. example-tab:: examples/c/io-file-remote/io-file-remote.c
+

 .. _s4u_ex_IPC:
 
 Classical synchronization objects
 ---------------------------------
 
 .. _s4u_ex_IPC:
 
 Classical synchronization objects
 ---------------------------------
 

- - **Mutex:**
-   Shows how to use simgrid::s4u::Mutex synchronization objects.
+ - **Barrier:**
+   Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.

 
    .. tabs::
 
 
    .. tabs::
 

-      .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
+      .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp

 
 

- - **Barrier:**
-   Shows how to use simgrid::s4u::Barrier synchronization objects.
+ - **Condition variable:**
+   Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.

 
    .. tabs::
 
 
    .. tabs::
 

-      .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
+      .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
+
+ - **Mutex:**
+   Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
+
+   .. tabs::
+
+      .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp

 
  - **Semaphore:**
 
  - **Semaphore:**

-   Shows how to use simgrid::s4u::Semaphore synchronization objects.
+   Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.

 
    .. tabs::
 
 
    .. tabs::
 


@@ -446,6 +573,13 @@ Interacting with the Platform
          - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
          - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 
          - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
          - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 

+      .. example-tab:: examples/c/platform-properties/platform-properties.c
+
+         - :cpp:func:`sg_actor_get_property()` and :cpp:func:`sg_actor_set_property()`
+         - :cpp:func:`sg_host_get_property()` and :cpp:func:sg_host_set_property()`
+         - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
+         - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
+

       .. group-tab:: XML
 
          **Deployment file:**
       .. group-tab:: XML
 
          **Deployment file:**


@@ -481,6 +615,8 @@ Interacting with the Platform
 
       .. example-tab:: examples/s4u/platform-failures/s4u-platform-failures.cpp
 
 
       .. example-tab:: examples/s4u/platform-failures/s4u-platform-failures.cpp
 

+      .. example-tab:: examples/c/platform-failures/platform-failures.c
+

       .. group-tab:: XML
 
          .. showfile:: examples/platforms/small_platform_failures.xml
       .. group-tab:: XML
 
          .. showfile:: examples/platforms/small_platform_failures.xml


@@ -515,14 +651,22 @@ Energy Simulation
 =================
 
   - **Describing the energy profiles in the platform:**
 =================
 
   - **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::
 
 
     .. 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
 
   - **Consumption due to the CPU:** 
     This example shows how to retrieve the amount of energy consumed


@@ -532,14 +676,24 @@ Energy Simulation
 
        .. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp
 
 
        .. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp
 

-  - **Consumption due to the network:**
+       .. example-tab:: examples/c/energy-exec/energy-exec.c
+
+  - **Consumption due to the wired network:**

     This example shows how to retrieve and display the energy consumed
     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
 
 
     .. 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.
   - **Modeling the shutdown and boot of hosts:**
     Simple example of model of model for the energy consumption during
     the host boot and shutdown periods.


@@ -563,13 +717,78 @@ options to see the task executions:
 
   - **Platform Tracing:**
     This program is a toy example just loading the platform, so that
 
   - **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
 
     ``--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
 ========================
 ========================
 Larger SimGrid Examplars
 ========================


@@ -586,6 +805,8 @@ than the previous examples.
 
        .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
 
 
        .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
 

+       .. example-tab:: examples/c/app-pingpong/app-pingpong.c
+

   - **Token ring:**
     Shows how to implement a classical communication pattern, where a
     token is exchanged along a ring to reach every participant.
   - **Token ring:**
     Shows how to implement a classical communication pattern, where a
     token is exchanged along a ring to reach every participant.


@@ -594,6 +815,8 @@ than the previous examples.
 
        .. example-tab:: examples/s4u/app-token-ring/s4u-app-token-ring.cpp
 
 
        .. example-tab:: examples/s4u/app-token-ring/s4u-app-token-ring.cpp
 

+       .. example-tab:: examples/c/app-token-ring/app-token-ring.c
+

   - **Master Workers:**
     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
     processes.
   - **Master Workers:**
     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
     processes.


@@ -613,6 +836,11 @@ than the previous examples.
 
           .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
              :language: cpp
 
           .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
              :language: cpp

+
+       .. group-tab:: C
+
+          .. showfile:: examples/c/app-masterworker/app-masterworker.c
+             :language: cpp

     
 Data diffusion
 --------------
     
 Data diffusion
 --------------


@@ -633,6 +861,17 @@ Data diffusion
           .. showfile:: examples/s4u/app-bittorrent/s4u-tracker.cpp
              :language: cpp
 
           .. showfile:: examples/s4u/app-bittorrent/s4u-tracker.cpp
              :language: cpp
 

+       .. group-tab:: C
+
+          .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
+             :language: cpp
+
+          .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
+             :language: cpp
+
+          .. showfile:: examples/c/app-bittorrent/tracker.c
+             :language: cpp
+

   - **Chained Send:** 
     Data broadcast over a ring of processes.
 
   - **Chained Send:** 
     Data broadcast over a ring of processes.
 


@@ -640,6 +879,17 @@ Data diffusion
 
        .. example-tab:: examples/s4u/app-chainsend/s4u-app-chainsend.cpp
 
 
        .. example-tab:: examples/s4u/app-chainsend/s4u-app-chainsend.cpp
 

+       .. group-tab:: C
+
+          .. showfile:: examples/c/app-chainsend/chainsend.c
+             :language: c
+
+          .. showfile:: examples/c/app-chainsend/broadcaster.c
+             :language: c
+
+          .. showfile:: examples/c/app-chainsend/peer.c
+             :language: c
+

 Distributed Hash Tables (DHT)
 -----------------------------
 
 Distributed Hash Tables (DHT)
 -----------------------------
 


@@ -675,6 +925,23 @@ Distributed Hash Tables (DHT)
           .. showfile:: examples/s4u/dht-kademlia/node.cpp
              :language: cpp
 
           .. showfile:: examples/s4u/dht-kademlia/node.cpp
              :language: cpp
 

+       .. group-tab:: C
+
+          .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
+             :language: cpp
+
+          .. showfile:: examples/c/dht-kademlia/routing_table.c
+             :language: cpp
+
+          .. showfile:: examples/c/dht-kademlia/answer.c
+             :language: cpp
+
+          .. showfile:: examples/c/dht-kademlia/message.c
+             :language: cpp
+
+          .. showfile:: examples/c/dht-kademlia/node.c
+             :language: cpp
+

 .. _s4u_ex_clouds:
 
 Simulating Clouds
 .. _s4u_ex_clouds:
 
 Simulating Clouds


@@ -688,6 +955,8 @@ Simulating Clouds
 
        .. example-tab:: examples/s4u/cloud-simple/s4u-cloud-simple.cpp
 
 
        .. example-tab:: examples/s4u/cloud-simple/s4u-cloud-simple.cpp
 

+       .. example-tab:: examples/c/cloud-simple/cloud-simple.c
+

   - **Migrating VMs**
     This example shows how to migrate VMs between PMs.
 
   - **Migrating VMs**
     This example shows how to migrate VMs between PMs.
 


@@ -695,6 +964,88 @@ Simulating Clouds
 
        .. example-tab:: examples/s4u/cloud-migration/s4u-cloud-migration.cpp
 
 
        .. example-tab:: examples/s4u/cloud-migration/s4u-cloud-migration.cpp
 

+       .. example-tab:: examples/c/cloud-migration/cloud-migration.c
+
+=======================
+Model-Related Examples
+=======================
+
+  - **ns-3 as a SimGrid Network Model**
+    This simple ping-pong example demonstrates how to use the bindings to the Network
+    Simulator. The most interesting is probably not the C++ files since
+    they are unchanged from the other simulations, but the associated files,
+    such as the platform file to see how to declare a platform to be used 
+    with the ns-3 bindings of SimGrid and the tesh file to see how to actually
+    start a simulation in these settings.
+
+    .. tabs::
+
+      .. example-tab:: examples/s4u/network-ns3/s4u-network-ns3.cpp
+
+      .. 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
 =======================
 =======================
 Model-Checking Examples
 =======================