.. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp
- .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
+ .. example-tab:: examples/python/comm-pingpong/comm-pingpong.py
+ .. 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
+Illustrates how to have non-blocking communications, that are communications running in the background leaving the process
free to do something else during their completion.
.. tabs::
See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
- .. example-tab:: examples/python/comm-waitfor/comm-waitfor.py
+ .. example-tab:: examples/python/comm-waituntil/comm-waituntil.py
+
+ See also :py:func:`simgrid.Comm.wait_until()`
+
+.. _s4u_ex_mailbox_ready:
+
+Checking for incoming communications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example uses ``Mailbox.ready()`` to check for completed communications. When this function returns true, then at least a message
+is arrived, so you know that ``Mailbox.get()`` will complete imediately. This is thus another way toward asynchronous communications.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/comm-ready/s4u-comm-ready.cpp
+
+ See also :cpp:func:`simgrid::s4u::Mailbox::ready()`.
+
+ .. example-tab:: examples/python/comm-ready/comm-ready.py
+
+ See also :py:func:`simgrid.Mailbox.ready()`
- See also :py:func:`simgrid.Comm.wait_for()` and :py:func:`simgrid.Comm.wait_any_for()`
Suspending communications
^^^^^^^^^^^^^^^^^^^^^^^^^
:cpp:func:`simgrid::s4u::Activity::resume()` and
:cpp:func:`simgrid::s4u::Activity::is_suspended()`.
+ .. example-tab:: examples/python/comm-suspend/comm-suspend.py
+
+ See also :py:func:`simgrid.Comm::suspend()` and
+ :py:func:`simgrid.Comm.resume()`.
+
Waiting for all communications in a set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See also :cpp:func:`simgrid::s4u::Comm::test_any()`.
+ .. example-tab:: examples/python/comm-testany/comm-testany.py
+
+ See also :py:func:`simgrid.Comm.test_any()`.
+
+.. _s4u_ex_comm_failure:
+
+Dealing with network failures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This examples shows how to survive to network exceptions that occur when a link is turned off, or when the actor with whom
+you communicate fails because its host is turned off. In this case, any blocking operation such as ``put``, ``get`` or
+``wait`` will raise an exception that you can catch and react to. See also :ref:`howto_churn`,
+:ref:`this example <s4u_ex_platform_state_profile>` on how to attach a state profile to hosts and
+:ref:`that example <s4u_ex_exec_failure>` on how to react to host failures.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/comm-failure/s4u-comm-failure.cpp
+
+ .. example-tab:: examples/python/comm-failure/comm-failure.py
+
+.. _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:
.. example-tab:: examples/python/exec-async/exec-async.py
See also :py:func:`simgrid.this_actor.exec_init()`,
- :py:func:`simgrid.Activity.start()`,
- :py:func:`simgrid.Activity.wait()`,
+ :py:func:`simgrid.Exec.start()`,
+ :py:func:`simgrid.Exec.wait()`,
:py:attr:`simgrid.Exec.remaining`,
:py:attr:`simgrid.Exec.remaining_ratio`,
:py:func:`simgrid.this_actor.exec_async()` and
- :py:func:`simgrid.Activity.cancel()`.
+ :py:func:`simgrid.Exec.cancel()`.
.. example-tab:: examples/c/exec-async/exec-async.c
^^^^^^^^^^^^^^^^
You can start executions on remote hosts, or even change the host on which they occur during their execution.
+This is naturally not very realistic, but it's something handy to have.
.. tabs::
See also :cpp:func:`sg_exec_set_host()`.
+.. _s4u_ex_ptasks:
+
Parallel executions
^^^^^^^^^^^^^^^^^^^
See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
+ .. example-tab:: examples/python/exec-ptask/exec-ptask.py
+
+ See also :ref:`simgrid.this_actor.parallel_execute()`
+
+Ptasks play well with the host energy plugin, as shown in this example.
+There is not much new compared to the above ptask example or the
+:ref:`examples about energy <s4u_ex_energy>`. It just works.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/energy-exec-ptask/s4u-energy-exec-ptask.cpp
+
+ .. example-tab:: examples/c/energy-exec-ptask/energy-exec-ptask.c
+
+.. _s4u_ex_exec_failure:
+
+Dealing with host failures
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This examples shows how to survive to host failure exceptions that occur when an host is turned off. The actor do not get notified when the host
+on which they run is turned off: they are just terminated in this case, and their ``on_exit()`` callback gets executed. For remote executions on
+failing hosts however, any blocking operation such as ``exec`` or ``wait`` will raise an exception that you can catch and react to. See also
+:ref:`howto_churn`,
+:ref:`this example <s4u_ex_platform_state_profile>` on how to attach a state profile to hosts, and
+:ref:`that example <s4u_ex_comm_failure>` on how to react to networ failures.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/exec-failure/s4u-exec-failure.cpp
+
+.. _s4u_ex_dvfs:
+
DVFS and pstates
^^^^^^^^^^^^^^^^
.. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
- See also :py:attr:`Host.pstate_speed` and :py:func:`Host.set_pstate()`.
+ See also :py:func:`simgrid.Host.pstate_speed()` and :py:attr:`simgrid.Host.pstate`.
.. 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
.. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
+ .. example-tab:: examples/python/synchro-barrier/synchro-barrier.py
+
Condition variable: basic usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
+ .. example-tab:: examples/python/synchro-semaphore/synchro-semaphore.py
+
.. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
=============================
Profiles
--------
+.. _s4u_ex_platform_state_profile:
+
Specifying state profiles
^^^^^^^^^^^^^^^^^^^^^^^^^
Shows how to specify when the resources must be turned off and on again, and how to react to such
-failures in your code. See also :ref:`howto_churn`.
+failures in your code. See also :ref:`howto_churn`,
+:ref:`this example <s4u_ex_comm_failure>` on how to react to communication failures, and
+:ref:`that example <s4u_ex_exec_failure>` on how to react to host failures.
.. tabs::
.. example-tab:: examples/c/platform-failures/platform-failures.c
+ .. example-tab:: examples/python/platform-failures/platform-failures.py
+
.. group-tab:: XML
.. showfile:: examples/platforms/small_platform_failures.xml
.. 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()`.
+
+.. _s4u_ex_energy:
+
=================
Energy Simulation
=================
Master Workers
^^^^^^^^^^^^^^
-Another good old example, where one Master acto$ has a bunch of tasks to dispatch to a set of several Worker actors.
+Another good old example, where one Master actor has a bunch of tasks to dispatch to a set of several Worker actors.
This example is used in the :ref:`SimGrid tutorial <usecase_simalgo>`.
.. tabs::
.. showfile:: examples/c/app-masterworker/app-masterworker.c
:language: cpp
+ .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
+
Data diffusion
--------------
.. showfile:: examples/platforms/wifi.xml
:language: xml
+
+
===============
Plugin Examples
===============
