-.. S4U (Simgrid for you) is the modern interface of SimGrid, which new project should use.
+.. S4U (SimGrid for you) is the modern interface of SimGrid, which new project should use.
..
.. This file follows the ReStructured syntax to be included in the
.. documentation, but it should remain readable directly.
------------------------------------
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.
+is arrived, so you know that ``Mailbox.get()`` will complete immediately. This is thus another way toward asynchronous communications.
.. tabs::
.. example-tab:: examples/python/comm-suspend/comm-suspend.py
- See also :py:func:`simgrid.Comm::suspend()` and
+ See also :py:func:`simgrid.Comm.suspend()` and
:py:func:`simgrid.Comm.resume()`.
-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 been completed.
-
-.. tabs::
-
- .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
-
- See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
-
- .. example-tab:: examples/python/comm-waitall/comm-waitall.py
-
- 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()`` blocks until one activity of the set completes, no matter which terminates first.
-
-.. tabs::
-
- .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
-
- See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
-
- .. example-tab:: examples/python/comm-waitany/comm-waitany.py
-
- 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`.
-
-Testing whether at least one communication completed
-----------------------------------------------------
-
-The ``test_any()`` returns whether at least one activity of the set has completed, or -1.
-
-.. tabs::
-
- .. example-tab:: examples/cpp/comm-testany/s4u-comm-testany.cpp
-
- 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
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.
+:ref:`that example <s4u_ex_comm_failure>` on how to react to network failures.
.. tabs::
.. example-tab:: examples/c/io-file-remote/io-file-remote.c
+.. _s4u_ex_activityset:
+
+Bags of activities
+==================
+
+Sometimes, you want to block on a set of activities, getting unblocked when any activity of the set unblocks, or waiting for the
+completion of all activities in the set. This is where the ActivitySet become useful.
+
+Waiting for all activities in a set
+-----------------------------------
+
+The ``wait_all()`` function is useful when you want to block until all activities in a given set have been completed.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/activityset-waitall/s4u-activityset-waitall.cpp
+
+ See also :cpp:func:`simgrid::s4u::ActivitySet::wait_all()`.
+
+ .. example-tab:: examples/python/activityset-waitall/activityset-waitall.py
+
+ See also :py:func:`simgrid.ActivitySet.wait_all()`.
+
+ .. example-tab:: examples/c/activityset-waitall/activityset-waitall.c
+
+ See also :cpp:func:`sg_activityset_wait_all()`.
+
+Waiting for all activities in a set (with timeout)
+--------------------------------------------------
+
+The ``wait_all_for()`` function is very similar to ``wait_all()`` but allows to specify a timeout.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/activityset-waitallfor/s4u-activityset-waitallfor.cpp
+
+ See also :cpp:func:`simgrid::s4u::ActivitySet::wait_all_for()`.
+
+ .. example-tab:: examples/python/activityset-waitallfor/activityset-waitallfor.py
+
+ See also :py:func:`simgrid.ActivitySet.wait_all_for()`.
+
+ .. example-tab:: examples/c/activityset-waitallfor/activityset-waitallfor.c
+
+ See also :cpp:func:`sg_activityset_wait_all_for()`.
+
+Waiting for the first completed activity in a set
+-------------------------------------------------
+
+The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/activityset-waitany/s4u-activityset-waitany.cpp
+
+ See also :cpp:func:`simgrid::s4u::ActivitySet::wait_any()`.
+
+ .. example-tab:: examples/python/activityset-waitany/activityset-waitany.py
+
+ See also :py:func:`simgrid.ActivitySet.wait_any()`.
+
+ .. example-tab:: examples/c/activityset-waitany/activityset-waitany.c
+
+ See also :cpp:func:`sg_activityset_wait_any`.
+
+Testing whether at least one activity completed
+-----------------------------------------------
+
+The ``test_any()`` returns whether at least one activity of the set has completed.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/activityset-testany/s4u-activityset-testany.cpp
+
+ See also :cpp:func:`simgrid::s4u::ActivitySet::test_any()`.
+
+ .. example-tab:: examples/python/activityset-testany/activityset-testany.py
+
+ See also :py:func:`simgrid.ActivitySet.test_any()`.
+
+ .. example-tab:: examples/c/activityset-testany/activityset-testany.c
+
+ See also :cpp:func:`sg_activityset_test_any`.
+
.. _s4u_ex_dag:
-DAG of activities
-=================
+Dependencies between activities
+===============================
-SimGrid makes it easy to express dependencies between activities, where a given activity cannot start until the completion of all its predecessors.
-You can even have simulation not involving any actors, where the main thread (called maestro) creates and schedules activities itself.
+SimGrid makes it easy to express dependencies between activities, where a given activity cannot start until the completion of
+all its predecessors. You can even have simulation not involving any actors, where the main thread (called maestro) creates and
+schedules activities itself.
+
+Simple dependencies
+-------------------
+
+When you declare dependencies between two activities, the dependent will not actually start until all its dependencies complete,
+as shown in the following examples. The first one declare dependencies between executions while the second one declare
+dependencies between communications. You could declare such dependencies between arbitrary activities.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/exec-dependent/s4u-exec-dependent.cpp
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/comm-dependent/s4u-comm-dependent.cpp
+
+Assigning activities
+--------------------
+
+To actually start, an activity needs to be assigned to a given resource. This examples illustrates how an execution that is not
+assigned will not actually start until being assigned. In some sense, activities' assignment can be seen as a specific
+dependency that can withdraw their execution.
+
+.. tabs::
+
+ .. example-tab:: examples/cpp/exec-unassigned/s4u-exec-unassigned.cpp
Simple DAG of activities
------------------------
-This example shows how to create activities organized as a DAG (direct acyclic graph), and start them.
+This example shows how to create activities from the maestro directly without relying on an actor, organize the dependencies of
+activities as a DAG (direct acyclic graph), and start them. Each activity will start as soon as its dependencies are fulfilled.
.. tabs::
.. example-tab:: examples/cpp/dag-io/s4u-dag-io.cpp
-Assigning activities
---------------------
-
-To actually start, an activity needs to be assigned to a given resource. This examples illustrates how an execution that is not assigned will not actually start until being assigned.
-
-.. tabs::
-
- .. example-tab:: examples/cpp/exec-unassigned/s4u-exec-unassigned.cpp
-
Scheduling activities
---------------------
Loading DAGs from file
----------------------
-There is currently two file formats that you can load directly in SimGrid, but writting another loader for your beloved format should not be difficult.
+There is currently two file formats that you can load directly in SimGrid, but writing another loader for your beloved format should not be difficult.
.. tabs::
.. example-tab:: examples/cpp/dag-failure/s4u-dag-failure.cpp
-DAGs and actors
----------------
-
-You can also declare dependencies to regular activities that are executed by actors, as shown in the following examples.
-The first one declare dependencies between executions while the second one declare dependencies between communications.
-You could declare such dependencies between arbitrary activities.
-
-.. tabs::
-
- .. example-tab:: examples/cpp/exec-dependent/s4u-exec-dependent.cpp
-
-.. tabs::
-
- .. example-tab:: examples/cpp/comm-dependent/s4u-comm-dependent.cpp
-
.. _s4u_ex_IPC:
Classical synchronization objects
