From 1a0b456abcc5188a31ba979c6ddafb20fc38163d Mon Sep 17 00:00:00 2001 From: Fred Suter Date: Wed, 21 Jun 2023 17:25:46 -0400 Subject: [PATCH] [ci-skip] document s4u::Task --- docs/source/app_s4u.rst | 242 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 235 insertions(+), 7 deletions(-) diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index e5148affab..4a0f3fe0a5 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -96,6 +96,9 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Activities| replace:: **Activities** .. _API_s4u_Activities: #api-s4u-activity +.. |API_s4u_Tasks| replace:: **Tasks** +.. _API_s4u_Tasks: #api-s4u-task + .. |API_s4u_Hosts| replace:: **Hosts** .. _API_s4u_Hosts: #api-s4u-host @@ -187,13 +190,39 @@ with :cpp:func:`s4u::Comm::wait_all() `. :dedent: 2 ===================== -Activities Life cycle +Activities Life Cycle ===================== Sometimes, you want to change the setting of an activity before it even starts. .. todo:: write this section +===================== +Repeatable Activities +===================== + +In order to simulate the execution of Dataflow applications, we introduced the +concept of |API_s4u_Tasks|, that can be seen as repeatable activities. A Dataflow +is defined as a graph of |API_s4u_Tasks| through which circulate Tokens. Tokens +can carry any user-defined data, using the same internal mechanisms as for the +other simulated objects. Each Task has to receive a token from each of its +predecessor to fire a new instance of a |API_s4u_Comm|, |API_s4u_Exec|, or +|API_s4u_Io| activity. On completion of this activity, the Task propagates tokens +to its successors, and waits for the next set of tokens to arrive. + +To initiate the execution of a Dataflow, it is possible to some make +|API_s4u_Tasks| fire one or more activities without waiting for any token with the +:cpp:func:`s4u::Task::enqueue_firings() ` +function. + +The parameters and successors of a Task can be redefined at runtime by attaching +callbacks to the +:cpp:func:`s4u::Task::on_this_start ` +and +:cpp:func:`s4u::Task::on_this_completion ` +signals. + + .. _s4u_mailbox: Mailboxes @@ -2116,8 +2145,8 @@ Querying info .. group-tab:: C++ - .. doxygenfunction:: simgrid::s4u::Activity::get_cname - .. doxygenfunction:: simgrid::s4u::Activity::get_name + .. doxygenfunction:: simgrid::s4u::Activity::get_cname() const + .. doxygenfunction:: simgrid::s4u::Activity::get_name() const .. doxygenfunction:: simgrid::s4u::Activity::get_remaining() const .. doxygenfunction:: simgrid::s4u::Activity::get_state() const .. doxygenfunction:: simgrid::s4u::Activity::set_remaining(double remains) @@ -2310,11 +2339,11 @@ Signals .. group-tab:: C++ .. doxygenfunction:: simgrid::s4u::Comm::on_start_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_this_start_cb .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_this_completion_cb .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb - - .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb .. doxygenfunction:: simgrid::s4u::Comm::on_suspended_cb .. doxygenfunction:: simgrid::s4u::Comm::on_resumed_cb .. doxygenfunction:: simgrid::s4u::Comm::on_veto_cb @@ -2453,9 +2482,10 @@ Signals .. group-tab:: C++ .. doxygenfunction:: simgrid::s4u::Exec::on_start_cb + .. doxygenfunction:: simgrid::s4u::Exec::on_this_start_cb .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Exec::on_this_completion_cb - .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb .. doxygenfunction:: simgrid::s4u::Exec::on_suspended_cb .. doxygenfunction:: simgrid::s4u::Exec::on_resumed_cb .. doxygenfunction:: simgrid::s4u::Exec::on_veto_cb @@ -2529,13 +2559,211 @@ Signals .. group-tab:: C++ .. doxygenfunction:: simgrid::s4u::Io::on_start_cb + .. doxygenfunction:: simgrid::s4u::Io::on_this_start_cb .. doxygenfunction:: simgrid::s4u::Io::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Io::on_this_completion_cb - .. doxygenfunction:: simgrid::s4u::Io::on_completion_cb .. doxygenfunction:: simgrid::s4u::Io::on_suspended_cb .. doxygenfunction:: simgrid::s4u::Io::on_resumed_cb .. doxygenfunction:: simgrid::s4u::Io::on_veto_cb + +.. _API_s4u_Tasks: + +========== +Tasks +========== + +============== +class Task +============== + +.. doxygenclass:: simgrid::s4u::Task + +**Known subclasses:** +:ref:`Communication Tasks `, +:ref:`Executions Tasks `, +:ref:`I/O Tasks `. +See also the :ref:`section on activities ` above. + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: TaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_cname() const + .. doxygenfunction:: simgrid::s4u::Task::get_name() const + .. doxygenfunction:: simgrid::s4u::Task::get_count() const + .. doxygenfunction:: simgrid::s4u::Task::get_amount() const + .. doxygenfunction:: simgrid::s4u::Task::set_amount(double amount) + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Task::enqueue_firings(int n) + +Managing Dependencies +--------------------- +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Task::add_successor(TaskPtr t) + .. doxygenfunction:: simgrid::s4u::Task::remove_successor(TaskPtr t) + .. doxygenfunction:: simgrid::s4u::Task::remove_all_successors() + .. doxygenfunction:: simgrid::s4u::Task::get_successors() const + +Managing Tokens +--------------- +.. doxygenclass:: simgrid::s4u::Token + +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Task::set_token(std::shared_ptr token) + .. doxygenfunction:: simgrid::s4u::Task::get_next_token_from(TaskPtr t) + +Signals +------- + +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Task::on_start_cb + .. doxygenfunction:: simgrid::s4u::Task::on_this_start_cb + .. doxygenfunction:: simgrid::s4u::Task::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Task::on_this_completion_cb + +.. _API_s4u_CommTask: + +================ +⁣  class CommTask +================ +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::CommTask + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: CommTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_source() const + .. doxygenfunction:: simgrid::s4u::Task::get_destination() const + .. doxygenfunction:: simgrid::s4u::Task::get_bytes() const + .. doxygenfunction:: simgrid::s4u::Task::set_source(simgrid::s4u::Host* source); + .. doxygenfunction:: simgrid::s4u::Task::set_destination(simgrid::s4u::Host* destination); + .. doxygenfunction:: simgrid::s4u::Task::set_bytes(double bytes) + + +.. _API_s4u_ExecTask: + +================ +⁣  class ExecTask +================ +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::ExecTask + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: ExecTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_host() const + .. doxygenfunction:: simgrid::s4u::Task::get_flops() const + .. doxygenfunction:: simgrid::s4u::Task::set_host(simgrid::s4u::Host* host); + .. doxygenfunction:: simgrid::s4u::Task::set_flops(double flops); + +.. _API_s4u_IoTask: + +================ +⁣  class IoTask +================ +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::IoTask + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: IoTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_disk() const + .. doxygenfunction:: simgrid::s4u::Task::get_bytes() const + .. doxygenfunction:: simgrid::s4u::Task::get_op_type() const + .. doxygenfunction:: simgrid::s4u::Task::set_disk(simgrid::s4u::Disk* disk); + .. doxygenfunction:: simgrid::s4u::Task::set_bytes(simgrid::double bytes); + .. doxygenfunction:: simgrid::s4u::Task::set_op_type(simgrid::s4u::Io::OpType type); + .. _API_s4u_Synchronizations: ======================= -- 2.20.1