Move an example to the right section, and document it

[simgrid.git] / examples / README.rst

diff --git a/examples/README.rst b/examples/README.rst
index eff074b..16b544b 100644 (file)
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -323,7 +323,6 @@ the simulators (as detailed in Section :ref:`options`).
 
    .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
 
-
 Basic asynchronous communications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -431,6 +430,24 @@ The ``test_any()`` returns whether at least one activity of the set has complete
 
       See also :py:func:`simgrid.Comm.test_any()`.
 
+.. _s4u_ex_comm_host2host:
+
+Direct host-to-host communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example demonstrates the direct communication mechanism, that allows to send data from one host to another without
+relying on the mailbox mechanism.
+
+.. tabs::
+
+   .. example-tab:: examples/cpp/comm-host2host/s4u-comm-host2host.cpp
+
+      See also :cpp:func:`simgrid::s4u::Comm::sendto_init()` and  :cpp:func:`simgrid::s4u::Comm::sendto_async()`.
+
+   .. example-tab:: examples/python/comm-host2host/comm-host2host.py
+
+      See also :py:func:`simgrid.Comm.sendto_init()` and  :py:func:`simgrid.Comm.sendto_async()`.
+
 .. _s4u_ex_execution:
 
 Executions on the CPU
@@ -544,6 +561,8 @@ This allows simulating malleable tasks.
 
       See also :ref:`simgrid.this_actor.parallel_execute()`
 
+.. _s4u_ex_dvfs:
+
 DVFS and pstates
 ^^^^^^^^^^^^^^^^
 
@@ -566,6 +585,10 @@ of a host can then be accessed and changed from the program.
 
    .. example-tab:: examples/platforms/energy_platform.xml
 
+      The important parts are in the :ref:`pf_tag_host` tag. The ``pstate`` attribute is the initial pstate while the ``speed`` attribute must
+      be a comma-separated list of values: the speed at each pstate. This platform file also describes the ``wattage_per_state`` and
+      ``wattage_off`` properties, that are used by the :ref:`plugin_host_energy` plugin.
+
 .. _s4u_ex_disk_io:
 
 I/O on Disks and Files
@@ -776,6 +799,28 @@ Shows how to specify an external load to resources, variating their peak speed o
 
          .. showfile:: examples/platforms/profiles/link1_latency.profile
 
+Modifying the platform
+----------------------
+
+Serializing communications 
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example shows how to limit the amount of communications going through a given link.
+It is very similar to the other asynchronous communication examples, but messages get serialized by the platform.
+Without this call to ``Link::set_concurrency_limit(2)``, all messages would be received at the exact same timestamp since
+they are initiated at the same instant and are of the same size. But with this extra configuration to the link, at most 2 
+messages can travel through the link at the same time.
+
+.. tabs::
+
+   .. example-tab:: examples/cpp/platform-comm-serialize/s4u-platform-comm-serialize.cpp
+
+      See also :cpp:func:`simgrid::s4u::Link::set_concurrency_limit()`.
+
+   .. example-tab:: examples/python/platform-comm-serialize/platform-comm-serialize.py
+
+      See also :py:func:`simgrid.Link.set_concurrency_limit()`.
+
 =================
 Energy Simulation
 =================