- :ref:`class Comm <API_s4u_Comm>`: Communication activity, started on Mailboxes and consuming links.
- :ref:`class Exec <API_s4u_Exec>`: Computation activity, started on Host and consuming CPU resources.
- :ref:`class Io <API_s4u_Io>`: I/O activity, started on and consuming disks.
+ - :ref:`class ActivtySet <API_s4u_ActivitySet>`: Bag of activities, to wait for any of the set, or all of them.
- **Synchronization Objects**: Classical IPC that actors can use
:cpp:func:`s4u::Disk::write_async() <simgrid::s4u::Disk::write_async>`; and
:ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
:cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
-In the future, it will become possible to have asynchronous IPC such as asynchronous mutex lock requests.
-
-The following example shows how to have several concurrent
-communications ongoing. First, you have to declare a vector in which
-we will store the ongoing communications. It is also useful to have a
-vector of mailboxes.
-
-.. literalinclude:: ../../examples/cpp/comm-waitall/s4u-comm-waitall.cpp
- :language: c++
- :start-after: init-begin
- :end-before: init-end
- :dedent: 2
-
-Then, you start all the communications that should occur concurrently with
-:cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.
-Finally, the actor waits for the completion of all of them at once
-with :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.
-
-.. literalinclude:: ../../examples/cpp/comm-waitall/s4u-comm-waitall.cpp
- :language: c++
- :start-after: put-begin
- :end-before: put-end
- :dedent: 2
+In the future, it will become possible to have asynchronous IPC such as asynchronous mutex lock requests (it is already possible
+internally, but the interface is not exposed in S4U yet).
+
+If you want for the completion of any activity in a given set, to react to the earlier occuring completion, then you need an
+:ref:`activity set <API_s4u_ActivitySet>`. Please refer to the :ref:`relevant examples <s4u_ex_activityset>` for more information.
=====================
Activities Life Cycle
in SimGrid, you'd have one mailbox per potential topic, and subscribe
to each topic individually with a
:cpp:func:`get_async() <simgrid::s4u::Mailbox::get_async>` on each mailbox.
-Then, use :cpp:func:`Comm::wait_any() <simgrid::s4u::Comm::wait_any>`
-to get the first message on any of the mailboxes you are subscribed to.
+Then, use an :ref:`class ActivtySet <API_s4u_ActivitySet>` to get the first
+message on any of the mailboxes you are subscribed to.
The mailboxes are not located on the network, and you can access
them without any latency. The network delays are only related to the
.. doxygenfunction:: simgrid::s4u::Comm::cancel
.. doxygenfunction:: simgrid::s4u::Comm::start
.. doxygenfunction:: simgrid::s4u::Comm::test
- .. doxygenfunction:: simgrid::s4u::Comm::test_any(const std::vector< CommPtr >& comms)
.. doxygenfunction:: simgrid::s4u::Comm::wait
- .. doxygenfunction:: simgrid::s4u::Comm::wait_all(const std::vector< CommPtr >& comms)
- .. doxygenfunction:: simgrid::s4u::Comm::wait_all_for(const std::vector< CommPtr >& comms, double timeout)
- .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr >& comms)
- .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr >& comms, double timeout)
.. doxygenfunction:: simgrid::s4u::Comm::wait_for
.. doxygenfunction:: simgrid::s4u::Comm::wait_until
.. automethod:: simgrid.Comm.cancel
.. automethod:: simgrid.Comm.start
.. automethod:: simgrid.Comm.test
- .. automethod:: simgrid.Comm.test_any
.. automethod:: simgrid.Comm.wait
.. automethod:: simgrid.Comm.wait_for
- .. automethod:: simgrid.Comm.wait_all
- .. automethod:: simgrid.Comm.wait_all_for
- .. automethod:: simgrid.Comm.wait_any
- .. automethod:: simgrid.Comm.wait_any_for
.. automethod:: simgrid.Comm.wait_until
.. group-tab:: C
.. doxygenfunction:: sg_comm_test
.. doxygenfunction:: sg_comm_wait
- .. doxygenfunction:: sg_comm_wait_all
- .. doxygenfunction:: sg_comm_wait_any
Suspending and resuming a communication
---------------------------------------
.. autoclass:: simgrid.Exec
+ .. group-tab:: C
+
+ .. doxygentypedef:: sg_exec_t
+ .. doxygentypedef:: const_sg_exec_t
+
Basic management
----------------
#include <simgrid/exec.h>
- .. doxygentypedef:: sg_exec_t
- .. doxygentypedef:: const_sg_exec_t
-
Querying info
-------------
.. doxygenfunction:: simgrid::s4u::Exec::start
.. doxygenfunction:: simgrid::s4u::Exec::test
.. doxygenfunction:: simgrid::s4u::Exec::wait
- .. doxygenfunction:: simgrid::s4u::Exec::wait_any(const std::vector< ExecPtr >& execs)
- .. doxygenfunction:: simgrid::s4u::Exec::wait_any_for(const std::vector< ExecPtr >& execs, double timeout)
- .. doxygenfunction:: simgrid::s4u::Exec::wait_for
.. group-tab:: Python
.. doxygenfunction:: sg_exec_cancel(sg_exec_t exec);
.. doxygenfunction:: sg_exec_test(sg_exec_t exec);
.. doxygenfunction:: sg_exec_wait(sg_exec_t exec);
- .. doxygenfunction:: sg_exec_wait_for(sg_exec_t exec, double timeout);
- .. doxygenfunction:: sg_exec_wait_any_for(sg_exec_t* execs, size_t count, double timeout);
- .. doxygenfunction:: sg_exec_wait_any(sg_exec_t* execs, size_t count);
Suspending and resuming an execution
------------------------------------
.. doxygenfunction:: simgrid::s4u::Io::start
.. doxygenfunction:: simgrid::s4u::Io::test
.. doxygenfunction:: simgrid::s4u::Io::wait
- .. doxygenfunction:: simgrid::s4u::Io::wait_for
- .. doxygenfunction:: simgrid::s4u::Io::wait_any(const std::vector<IoPtr> &ios)
- .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector<IoPtr> &ios, double timeout)
.. group-tab:: Python
.. automethod:: simgrid.Io.test
.. automethod:: simgrid.Io.wait
- .. automethod:: simgrid.Io.wait_any_for
- .. automethod:: simgrid.Io.wait_any
Signals
-------
.. doxygenfunction:: simgrid::s4u::Io::on_resumed_cb
.. doxygenfunction:: simgrid::s4u::Io::on_veto_cb
+.. _API_s4u_ActivitySet:
+
+====================
+ class ActivitySet
+====================
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. doxygenclass:: simgrid::s4u::ActivitySet
+
+ .. group-tab:: Python
+
+ .. autoclass:: simgrid.ActivitySet
+
+ .. group-tab:: C
+
+ .. doxygentypedef:: sg_activityset_t
+ .. doxygentypedef:: const_sg_activityset_t
+
+Basic management
+----------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. code-block:: C++
+
+ #include <simgrid/s4u/ActivitySet.hpp>
+
+ .. doxygentypedef:: ActivitySetPtr
+
+ .. group-tab:: Python
+
+ .. code:: Python
+
+ from simgrid import ActivitySet
+
+ .. group-tab:: C
+
+ .. code-block:: C
+
+ #include <simgrid/activity_set.h>
+
+ .. doxygenfunction:: sg_activity_set_init
+ .. doxygenfunction:: sg_activity_set_delete
+
+Managing activities
+-------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::push
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::erase
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::empty
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::size
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.ActivitySet.push()
+ .. automethod:: simgrid.ActivitySet.erase()
+ .. automethod:: simgrid.ActivitySet.empty()
+ .. automethod:: simgrid.ActivitySet.size()
+
+ .. group-tab:: c
+
+ .. doxygenfunction:: sg_activity_set_push
+ .. doxygenfunction:: sg_activity_set_erase
+ .. doxygenfunction:: sg_activity_set_empty
+ .. doxygenfunction:: sg_activity_set_size
+
+Interacting with the set
+------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::test_any
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::wait_all
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::wait_all_for
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::wait_any
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::wait_any_for
+
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.ActivitySet.test_any()
+ .. automethod:: simgrid.ActivitySet.wait_all()
+ .. automethod:: simgrid.ActivitySet.wait_all_for()
+ .. automethod:: simgrid.ActivitySet.wait_any()
+ .. automethod:: simgrid.ActivitySet.wait_any_for()
+
+ .. group-tab:: c
+
+ .. doxygenfunction:: sg_activity_set_test_any
+ .. doxygenfunction:: sg_activity_set_wait_all
+ .. doxygenfunction:: sg_activity_set_wait_all_for
+ .. doxygenfunction:: sg_activity_set_wait_any
+ .. doxygenfunction:: sg_activity_set_wait_any_for
+ .. doxygenfunction:: sg_activity_unref
+
+Dealing with failed activities
+------------------------------
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::get_failed_activity()
+ .. doxygenfunction:: simgrid::s4u::ActivitySet::has_failed_activities()
.. _API_s4u_Tasks:
.. doxygentypedef:: MutexPtr
- .. doxygenfunction:: simgrid::s4u::Mutex::create()
+ .. doxygenfunction:: simgrid::s4u::Mutex::create
.. group-tab:: Python
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
.. 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:
Dependencies between activities