Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
update doc
[simgrid.git] / docs / source / app_s4u.rst
index 42bf128..a44f8a1 100644 (file)
@@ -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,48 @@ with :cpp:func:`s4u::Comm::wait_all() <simgrid::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|, where each |API_s4u_Tasks| has a set of
+successors and predecessors. When a |API_s4u_Tasks| ends it sends a token to each
+of its successors. Each |API_s4u_Tasks| has to receive a token from each of its
+predecessor to start. Tokens can carry any user-defined data.
+
+|API_s4u_Tasks| are composed of several instances: a dispatcher, a collector, and
+instance_0 to instance_n. The dispatcher rely on a load balancing function to select
+the next instance to fire. Once this instance finishes it fires the collector.
+
+Each instance of an |API_s4u_ExecTask| can be placed on a different host.
+|API_s4u_Comm| activities are automatically created when an instance triggers
+another instance on a different host. Each instance has its own parallelism degree
+to scale horizontally on several cores.
+
+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() <simgrid::s4u::Task::enqueue_firings>`
+function.
+
+The parameters of Tasks can be redefined at runtime by attaching
+callbacks to the
+:cpp:func:`s4u::Task::on_this_start <simgrid::s4u::Task::on_this_start>`
+and
+:cpp:func:`s4u::Task::on_this_completion <simgrid::s4u::Task::on_this_completion>`
+signals. The former is triggered by instances others than the dispatcher and the collector,
+and the latter is triggered by the collector.
+
+
+
 .. _s4u_mailbox:
 
 Mailboxes
@@ -367,10 +405,6 @@ pointers (yet?). This means that it is currently impossible to destroy a
 mailbox or a link. You can still destroy a host (but probably
 shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
 
-.. THE EXAMPLES
-
-.. include:: ../../examples/README.rst
-
 API Reference
 *************
 
@@ -396,7 +430,7 @@ Simulation objects
 
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Actor
 
 Basic management
@@ -616,12 +650,19 @@ Signals
 
       .. doxygenfunction:: simgrid::s4u::Actor::on_creation_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_suspend_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_suspend_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_host_change_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_host_change_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_resume_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_resume_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_sleep_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_sleep_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_wake_up_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_wake_up_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_termination_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_termination_cb
       .. doxygenfunction:: simgrid::s4u::Actor::on_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Actor::on_this_destruction_cb
 
 .. _API_s4u_this_actor:
 
@@ -790,7 +831,7 @@ Exiting
       .. doxygenclass:: simgrid::s4u::Engine
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Engine
 
 Engin initialization
@@ -829,6 +870,7 @@ Simulation setup
 
       .. doxygenfunction:: simgrid::s4u::Engine::load_deployment
       .. doxygenfunction:: simgrid::s4u::Engine::load_platform
+      .. doxygenfunction:: simgrid::s4u::Engine::flatify_platform
       .. doxygenfunction:: simgrid::s4u::Engine::register_actor(const std::string &name)
       .. doxygenfunction:: simgrid::s4u::Engine::register_actor(const std::string &name, F code)
       .. doxygenfunction:: simgrid::s4u::Engine::register_default(const std::function< void(int, char **)> &code)
@@ -976,7 +1018,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::Mailbox
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Mailbox
 
 Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
@@ -1123,7 +1165,7 @@ Resources
       .. doxygenclass:: simgrid::s4u::Disk
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Disk
 
    .. group-tab:: C
@@ -1208,7 +1250,9 @@ Signals
 
       .. doxygenfunction:: simgrid::s4u::Disk::on_creation_cb
       .. doxygenfunction:: simgrid::s4u::Disk::on_destruction_cb
-      .. doxygenfunction:: simgrid::s4u::Disk::on_state_change_cb
+      .. doxygenfunction:: simgrid::s4u::Disk::on_this_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Disk::on_onoff_cb
+      .. doxygenfunction:: simgrid::s4u::Disk::on_this_onoff_cb
 
 
 .. _API_s4u_Host:
@@ -1224,7 +1268,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::Host
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Host
 
 Basic management
@@ -1472,7 +1516,7 @@ using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
 
       .. autoattribute:: simgrid.Host.netpoint
       .. automethod:: simgrid.Host.create_disk
-         
+
       .. automethod:: simgrid.Host.route_to
 
    .. group-tab:: C
@@ -1491,8 +1535,12 @@ Signals
 
       .. doxygenfunction:: simgrid::s4u::Host::on_creation_cb
       .. doxygenfunction:: simgrid::s4u::Host::on_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_this_destruction_cb
       .. doxygenfunction:: simgrid::s4u::Host::on_speed_change_cb
-      .. doxygenfunction:: simgrid::s4u::Host::on_state_change_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_this_speed_change_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_onoff_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_this_onoff_cb
+      .. doxygenfunction:: simgrid::s4u::Host::on_exec_state_change_cb
 
 .. _API_s4u_Link:
 
@@ -1510,7 +1558,7 @@ Signals
 
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Link
 
 Basic management
@@ -1586,6 +1634,7 @@ Querying info
       .. doxygenfunction:: simgrid::s4u::Link::get_latency() const
       .. doxygenfunction:: simgrid::s4u::Link::get_name() const
       .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const
+      .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const
       .. doxygenfunction:: simgrid::s4u::Link::get_usage() const
       .. doxygenfunction:: simgrid::s4u::Link::is_used() const
 
@@ -1702,10 +1751,13 @@ Signals
    .. group-tab:: C++
 
       .. doxygenfunction:: simgrid::s4u::Link::on_bandwidth_change_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_this_bandwidth_change_cb
       .. doxygenfunction:: simgrid::s4u::Link::on_communication_state_change_cb
       .. doxygenfunction:: simgrid::s4u::Link::on_creation_cb
       .. doxygenfunction:: simgrid::s4u::Link::on_destruction_cb
-      .. doxygenfunction:: simgrid::s4u::Link::on_state_change_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_this_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_onoff_cb
+      .. doxygenfunction:: simgrid::s4u::Link::on_this_onoff_cb
 
 .. _API_s4u_NetZone:
 
@@ -1720,7 +1772,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::NetZone
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.NetZone
 
 Basic management
@@ -2048,13 +2100,21 @@ Signals
 
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_creation_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_destruction_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_destruction_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_end_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_migration_end_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_migration_start_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_migration_start_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_resume_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_resume_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_shutdown_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_shutdown_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_start_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_start_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_started_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_started_cb
       .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_suspend_cb
+      .. doxygenfunction:: simgrid::s4u::VirtualMachine::on_this_suspend_cb
 
 .. _API_s4u_Activity:
 
@@ -2094,8 +2154,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)
@@ -2128,17 +2188,6 @@ Suspending and resuming an activity
       .. doxygenfunction:: simgrid::s4u::Activity::resume
       .. doxygenfunction:: simgrid::s4u::Activity::is_suspended
 
-Signals
--------
-
-.. tabs::
-
-   .. group-tab:: C++
-
-      .. doxygenfunction:: simgrid::s4u::Activity::on_completion_cb
-      .. doxygenfunction:: simgrid::s4u::Activity::on_suspended_cb
-      .. doxygenfunction:: simgrid::s4u::Activity::on_resumed_cb
-
 .. _API_s4u_Comm:
 
 =============
@@ -2152,7 +2201,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::Comm
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Comm
 
 Basic management
@@ -2274,6 +2323,23 @@ Life cycle
       .. doxygenfunction:: sg_comm_wait_all
       .. doxygenfunction:: sg_comm_wait_any
 
+Suspending and resuming a communication
+---------------------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenfunction:: simgrid::s4u::Comm::suspend
+      .. doxygenfunction:: simgrid::s4u::Comm::resume
+      .. doxygenfunction:: simgrid::s4u::Comm::is_suspended
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Comm.suspend
+      .. automethod:: simgrid.Comm.resume
+      .. autoattribute:: simgrid.Comm.is_suspended
+
 Signals
 -------
 
@@ -2282,9 +2348,14 @@ 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_suspended_cb
+      .. doxygenfunction:: simgrid::s4u::Comm::on_resumed_cb
+      .. doxygenfunction:: simgrid::s4u::Comm::on_veto_cb
 
 .. _API_s4u_Exec:
 
@@ -2299,7 +2370,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::Exec
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Exec
 
 Basic management
@@ -2395,6 +2466,23 @@ Life cycle
        .. 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
+------------------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenfunction:: simgrid::s4u::Exec::suspend
+      .. doxygenfunction:: simgrid::s4u::Exec::resume
+      .. doxygenfunction:: simgrid::s4u::Exec::is_suspended
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Exec.suspend
+      .. automethod:: simgrid.Exec.resume
+      .. autoattribute:: simgrid.Exec.is_suspended
+
 Signals
 -------
 
@@ -2403,7 +2491,13 @@ 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_suspended_cb
+      .. doxygenfunction:: simgrid::s4u::Exec::on_resumed_cb
+      .. doxygenfunction:: simgrid::s4u::Exec::on_veto_cb
 
 .. _API_s4u_Io:
 
@@ -2418,7 +2512,7 @@ Signals
       .. doxygenclass:: simgrid::s4u::Io
 
    .. group-tab:: Python
-   
+
       .. autoclass:: simgrid.Io
 
 Basic management
@@ -2474,7 +2568,210 @@ 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_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 <API_s4u_CommTask>`,
+:ref:`Executions Tasks <API_s4u_ExecTask>`,
+:ref:`I/O Tasks <API_s4u_Task>`.
+See also the :ref:`section on activities <s4u_Tasks>` above.
+
+Basic management
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. code-block:: C++
+
+         #include <simgrid/s4u/Task.hpp>
+
+      .. 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> 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 <simgrid/s4u/Task.hpp>
+
+      .. 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 <simgrid/s4u/Task.hpp>
+
+      .. 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 <simgrid/s4u/Task.hpp>
+
+      .. 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:
 
@@ -2786,7 +3083,7 @@ Error reporting
 
       The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
       exception go, so that the simulation stops. But you may want to catch them, for example when you launch
-      simgrid from a python notebook and want to handle the problem accordingly.
+      SimGrid from a python notebook and want to handle the problem accordingly.
 
       .. doxygenclass:: simgrid::AssertionError
       .. doxygenclass:: simgrid::ParseError
@@ -2805,7 +3102,7 @@ Error reporting
 
       The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
       exception go, so that the simulation stops. But you may want to catch them, for example when you launch
-      simgrid from a python notebook and want to handle the problem accordingly.
+      SimGrid from a python notebook and want to handle the problem accordingly.
 
       .. autoclass:: simgrid.AssertionError