.. |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
: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
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
*************
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Actor
Basic management
.. 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:
.. doxygenclass:: simgrid::s4u::Engine
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Engine
Engin initialization
.. 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)
.. doxygenclass:: simgrid::s4u::Mailbox
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Mailbox
Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
.. doxygenclass:: simgrid::s4u::Disk
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Disk
.. group-tab:: C
.. 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:
.. doxygenclass:: simgrid::s4u::Host
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Host
Basic management
.. autoattribute:: simgrid.Host.netpoint
.. automethod:: simgrid.Host.create_disk
-
+
.. automethod:: simgrid.Host.route_to
.. group-tab:: C
.. 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:
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Link
Basic management
.. 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
.. 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:
.. doxygenclass:: simgrid::s4u::NetZone
.. group-tab:: Python
-
+
.. autoclass:: simgrid.NetZone
Basic management
.. 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:
.. 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)
.. 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:
=============
.. doxygenclass:: simgrid::s4u::Comm
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Comm
Basic management
.. 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
-------
.. 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:
.. doxygenclass:: simgrid::s4u::Exec
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Exec
Basic management
.. 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
-------
.. 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:
.. doxygenclass:: simgrid::s4u::Io
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Io
Basic management
.. 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:
.. doxygenfunction:: sg_sem_release(sg_sem_t sem)
.. doxygenfunction:: sg_sem_would_block(const_sg_sem_t sem)
+===============
+Error reporting
+===============
+
+.. tabs::
+
+ .. group-tab:: C++
+
+ .. doxygenclass:: simgrid::Exception
+
+ The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
+
+ .. doxygenclass:: simgrid::CancelException
+ .. doxygenclass:: simgrid::HostFailureException
+ .. doxygenclass:: simgrid::NetworkFailureException
+ .. doxygenclass:: simgrid::StorageFailureException
+ .. doxygenclass:: simgrid::TimeoutException
+ .. doxygenclass:: simgrid::VmFailureException
+
+ 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.
+
+ .. doxygenclass:: simgrid::AssertionError
+ .. doxygenclass:: simgrid::ParseError
+ .. doxygenclass:: simgrid::TracingError
+
+ .. group-tab:: Python
+
+ The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
+
+ .. autoclass:: simgrid.CancelException
+ .. autoclass:: simgrid.HostFailureException
+ .. autoclass:: simgrid.NetworkFailureException
+ .. autoclass:: simgrid.StorageFailureException
+ .. autoclass:: simgrid.TimeoutException
+ .. autoclass:: simgrid.VmFailureException
+
+ 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.
+
+ .. autoclass:: simgrid.AssertionError
+
+ .. group-tab:: C
+
+ .. doxygenenum:: sg_error_t
+
+
.. |hr| raw:: html
<hr />
