From 8d9c110f5bf839dcb7426f7750c09b3ff196bdf3 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Thu, 16 Nov 2023 23:53:45 +0100 Subject: [PATCH] Document ActivitySet --- docs/source/Doxyfile | 1 + docs/source/Introduction.rst | 10 +- docs/source/Plugins.rst | 2 - docs/source/app_s4u.rst | 180 ++++++++++++++++++++-------- examples/README.rst | 137 +++++++++++++-------- include/simgrid/s4u/ActivitySet.hpp | 3 + 6 files changed, 220 insertions(+), 113 deletions(-) diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index 4f745520a3..fcf85af555 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -3,6 +3,7 @@ INPUT = ../../include/simgrid/forward.h INPUT += ../../include/simgrid/plugins/ INPUT += ../../include/simgrid/s4u/ INPUT += ../../include/simgrid/actor.h +INPUT += ../../include/simgrid/activity_set.h INPUT += ../../src/s4u/s4u_Actor.cpp INPUT += ../../include/simgrid/barrier.h INPUT += ../../include/simgrid/comm.h diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index 72c7c4ba60..32975c934f 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -34,8 +34,8 @@ Here are some objectives for which SimGrid is particularly relevant and has been quantify an application's performance behavior, but that instead explores all causally possible outcomes of the application so as to evaluate application correctness. This exhaustive search is ideal for finding bugs that are difficult to trigger experimentally. But because it is exhaustive, there is a limit to the scale of the applications for which it can be used. - Anatomy of a project that uses SimGrid ---------------------------------------- +Anatomy of a project that uses SimGrid +-------------------------------------- Any project that uses SimGrid as its simulation framework comprises the following components: @@ -46,10 +46,8 @@ Any project that uses SimGrid as its simulation framework comprises the followin disks, clusters, etc). SimGrid makes it straightforward to augment the simulated platform with dynamic behaviors where, for example, the links are slowed down (because of external usage) or the machines fail :ref:`(more info) `. - - An application's **deployment description**. To simulate the execution - of the application on the platform, they way in which the application is - deployed on the platform must be described. This is done by specifying - which process is mapped onto which machine :ref:`(more + - An application's **deployment description**. To simulate the execution of the application on the platform, they way in which the application is + deployed on the platform must be described. This is done by specifying which process is mapped onto which machine :ref:`(more info) `. - **Platform models**. SimGrid implements models that describe how the simulated platform reacts to the simulated activities performed my diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst index c40e5e61b9..4b879dd9de 100644 --- a/docs/source/Plugins.rst +++ b/docs/source/Plugins.rst @@ -209,8 +209,6 @@ Host Load .. doxygengroup:: plugin_host_load - - .. _plugin_filesystem: File System diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 8695720ee5..f12436c7f7 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -82,6 +82,7 @@ provides many helper functions to simplify the code of actors. - :ref:`class Comm `: Communication activity, started on Mailboxes and consuming links. - :ref:`class Exec `: Computation activity, started on Host and consuming CPU resources. - :ref:`class Io `: I/O activity, started on and consuming disks. + - :ref:`class ActivtySet `: Bag of activities, to wait for any of the set, or all of them. - **Synchronization Objects**: Classical IPC that actors can use @@ -165,29 +166,11 @@ Every kind of activity can be asynchronous. :cpp:func:`s4u::Disk::write_async() `; and :ref:`s4u::ExecPtr ` are created with :cpp:func:`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() `. -Finally, the actor waits for the completion of all of them at once -with :cpp:func:`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 `. Please refer to the :ref:`relevant examples ` for more information. ===================== Activities Life Cycle @@ -279,8 +262,8 @@ on the data you want to get from the mailbox. To model such settings in SimGrid, you'd have one mailbox per potential topic, and subscribe to each topic individually with a :cpp:func:`get_async() ` on each mailbox. -Then, use :cpp:func:`Comm::wait_any() ` -to get the first message on any of the mailboxes you are subscribed to. +Then, use an :ref:`class ActivtySet ` 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 @@ -2293,12 +2276,7 @@ Life cycle .. 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 @@ -2307,21 +2285,14 @@ Life cycle .. 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 --------------------------------------- @@ -2373,6 +2344,11 @@ Signals .. autoclass:: simgrid.Exec + .. group-tab:: C + + .. doxygentypedef:: sg_exec_t + .. doxygentypedef:: const_sg_exec_t + Basic management ---------------- @@ -2398,9 +2374,6 @@ Basic management #include - .. doxygentypedef:: sg_exec_t - .. doxygentypedef:: const_sg_exec_t - Querying info ------------- @@ -2445,9 +2418,6 @@ Life cycle .. 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 @@ -2462,9 +2432,6 @@ Life cycle .. 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 ------------------------------------ @@ -2549,16 +2516,11 @@ Life cycle .. 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 &ios) - .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector &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 ------- @@ -2576,6 +2538,120 @@ 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 + + .. doxygentypedef:: ActivitySetPtr + + .. group-tab:: Python + + .. code:: Python + + from simgrid import ActivitySet + + .. group-tab:: C + + .. code-block:: C + + #include + + .. 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: @@ -2811,7 +2887,7 @@ Basic management .. doxygentypedef:: MutexPtr - .. doxygenfunction:: simgrid::s4u::Mutex::create() + .. doxygenfunction:: simgrid::s4u::Mutex::create .. group-tab:: Python diff --git a/examples/README.rst b/examples/README.rst index 1370212e0d..991d2ace58 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -398,59 +398,6 @@ The ``suspend()`` and ``resume()`` functions block the progression of a given co 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 @@ -715,6 +662,90 @@ result in short reads and short writes, as in reality. .. 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 diff --git a/include/simgrid/s4u/ActivitySet.hpp b/include/simgrid/s4u/ActivitySet.hpp index 49c79d6fd3..10ec7c86ec 100644 --- a/include/simgrid/s4u/ActivitySet.hpp +++ b/include/simgrid/s4u/ActivitySet.hpp @@ -78,7 +78,10 @@ public: */ ActivityPtr wait_any() { return wait_any_for(-1); } + /** Return one of the failed activity of the set that was revealed during the previous wait operation, or + * ActivityPtr() if no failed activity exist in the set. */ ActivityPtr get_failed_activity(); + /** Return whether the set contains any failed activity. */ bool has_failed_activities() { return not failed_activities_.empty(); } // boost::intrusive_ptr support: -- 2.20.1