abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar
settings.
-Since v3.20 (June 2018), S4U is the way to go for long-term
-projects. It is feature complete, but may still evolve slightly in
-future releases. It can already be used to do everything that can be
-done in SimGrid, but you may have to adapt your code in future
-releases. When this happens, compiling your code will produce
-deprecation warnings for 4 releases (one year) before the removal of
-the old symbols.
-If you want an API that will never ever evolve in the future, you
-should use the :ref:`deprecated MSG API <MSG_doc>` instead.
+Since v3.33 (Spring 2023), S4U is the main interface of SimGrid for algorithms.
+It is feature complete, but may still evolve slightly in future releases.
+When this happens, compiling your code will produce deprecation warnings for 4
+releases (one year) before the removal of the old symbols.
+
+.. _S4U_main_concepts:
Main Concepts
*************
- :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
.. |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
: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
+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
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
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
.. group-tab:: C
+ .. doxygentypedef:: xbt_main_func_t
+
.. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, char *const *argv)
.. doxygenfunction:: sg_actor_init(const char *name, sg_host_t host)
.. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char *const *argv)
.. 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::Engine(int *argc, char **argv)
.. doxygenfunction:: simgrid::s4u::Engine::is_initialized()
- .. doxygenfunction:: simgrid::s4u::Engine::shutdown()
.. doxygenfunction:: simgrid::s4u::Engine::get_instance()
.. group-tab:: Python
.. 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
.. doxygenfunction:: sg_host_turn_off(sg_host_t host)
.. doxygenfunction:: sg_host_turn_on(sg_host_t host)
+.. _API_s4u_Host_dvfs:
+
DVFS
----
+See also the :ref:`relevant examples <s4u_ex_dvfs>`.
+
.. tabs::
.. group-tab:: C++
.. 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
#include <simgrid/link.h>
.. doxygentypedef:: sg_link_t
- .. cpp:type:: const s4u_Link* const_sg_link_t
-
- Pointer to a constant link object.
+ .. doxygentypedef:: const_sg_link_t
Retrieving links
----------------
.. 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_usage() const
+ .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const
+ .. doxygenfunction:: simgrid::s4u::Link::get_load() const
.. doxygenfunction:: simgrid::s4u::Link::is_used() const
.. group-tab:: Python
.. 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::NetZone::get_cname() const
.. doxygenfunction:: simgrid::s4u::NetZone::get_name() const
- .. doxygenfunction:: simgrid::s4u::NetZone::get_netpoint()
+ .. doxygenfunction:: simgrid::s4u::NetZone::get_netpoint
.. group-tab:: Python
.. group-tab:: C++
.. doxygenfunction:: simgrid::s4u::NetZone::add_component(kernel::routing::NetPoint *elm)
- .. doxygenfunction:: simgrid::s4u::NetZone::add_route
- .. doxygenfunction:: simgrid::s4u::NetZone::add_bypass_route
+ .. doxygenfunction:: simgrid::s4u::NetZone::add_route(const Host *src, const Host *dst, const std::vector< LinkInRoute > &link_list, bool symmetrical=true)
+ .. doxygenfunction:: simgrid::s4u::NetZone::add_route(const Host *src, const Host *dst, const std::vector< const Link * > &links)
+ .. doxygenfunction:: simgrid::s4u::NetZone::add_route(const NetZone *src, const NetZone *dst, const std::vector< LinkInRoute > &link_list, bool symmetrical=true)
+ .. doxygenfunction:: simgrid::s4u::NetZone::add_route(const NetZone *src, const NetZone *dst, const std::vector< const Link * > &links)
.. doxygenfunction:: simgrid::s4u::NetZone::get_children() const
.. doxygenfunction:: simgrid::s4u::NetZone::get_parent() const
.. doxygenfunction:: simgrid::s4u::NetZone::set_parent(const NetZone* parent)
.. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, double speed)
.. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::vector<std::string>& speed_per_pstate)
.. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string& name, const std::string& speed)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string &name, const std::string &speed)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string &name, const std::vector< double > &speed_per_pstate)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string &name, const std::vector< std::string > &speed_per_pstate)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_host(const std::string &name, double speed)
.. group-tab:: Python
.. group-tab:: C++
- .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<double>& bandwidths)
- .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, double bandwidth)
- .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::vector<std::string>& bandwidthds)
- .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string& name, const std::string& bandwidth)
- .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, const std::string& bandwidth)
- .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string& name, double bandwidth)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string &name, const std::vector< double > &bandwidths)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string &name, double bandwidth)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string &name, const std::vector< std::string > &bandwidths)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_link(const std::string &name, const std::string &bandwidth)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string &name, const std::string &bandwidth)
+ .. doxygenfunction:: simgrid::s4u::NetZone::create_split_duplex_link(const std::string &name, double bandwidth)
.. group-tab:: Python
.. 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:
.. doxygentypedef:: ActivityPtr
+ .. group-tab:: C
+
+ .. doxygentypedef:: sg_activity_t
+ .. doxygentypedef:: const_sg_activity_t
+
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)
.. doxygenfunction:: simgrid::s4u::Activity::wait
.. doxygenfunction:: simgrid::s4u::Activity::wait_for
.. doxygenfunction:: simgrid::s4u::Activity::wait_until(double time_limit)
- .. doxygenfunction:: simgrid::s4u::Activity::vetoable_start()
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:
=============
.. doxygenclass:: simgrid::s4u::Comm
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Comm
Basic management
.. automethod:: simgrid.Comm.set_payload_size
.. automethod:: simgrid.Comm.set_rate
-Life cycle
-----------
+Direct host-to-host communication
+---------------------------------
Most communications are created using :ref:`s4u_mailbox`, but you can
-also start direct communications as shown below.
+also start direct communications as shown below. See also the
+:ref:`relevant examples <s4u_ex_comm_host2host>`.
.. tabs::
.. doxygenfunction:: simgrid::s4u::Comm::sendto_init(Host *from, Host *to)
.. doxygenfunction:: simgrid::s4u::Comm::sendto_async
+ .. group-tab:: Python
+
+ .. automethod:: simgrid.Comm.sendto
+ .. automethod:: simgrid.Comm.sendto_init
+ .. automethod:: simgrid.Comm.sendto_async
+
+Life cycle
+----------
+
+.. tabs::
+
+ .. group-tab:: C++
+
.. 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
.. group-tab:: Python
- .. automethod:: simgrid.Comm.sendto
- .. automethod:: simgrid.Comm.sendto_init
- .. automethod:: simgrid.Comm.sendto_async
-
.. 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
+---------------------------------------
+
+.. 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_completion_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_start_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_suspend_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_resume_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_resumed_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_veto_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_completion_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_recv_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_resume_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_send_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_start_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_suspended_cb
+ .. doxygenfunction:: simgrid::s4u::Comm::on_this_veto_cb
.. _API_s4u_Exec:
.. doxygenclass:: simgrid::s4u::Exec
.. group-tab:: Python
-
+
.. 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
+------------------------------------
+
+.. 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
+ .. doxygenfunction:: simgrid::s4u::Exec::on_this_veto_cb
.. _API_s4u_Io:
.. doxygenclass:: simgrid::s4u::Io
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Io
Basic management
.. 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
-------
.. 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
+ .. doxygenfunction:: simgrid::s4u::Io::on_this_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_activity_set_t
+ .. doxygentypedef:: const_sg_activity_set_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:
+
+==========
+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_IoTask>`.
+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(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::Task::get_amount(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::Task::get_queued_firings(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::Task::get_running_count(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::Task::get_parallelism_degree(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::Task::set_name(std::string name)
+
+Life cycle
+----------
+
+.. tabs::
+
+ .. group-tab:: C++
+ .. doxygenfunction:: simgrid::s4u::Task::enqueue_firings(int n)
+ .. doxygenfunction:: simgrid::s4u::Task::set_amount(double amount, std::string instance)
+ .. doxygenfunction:: simgrid::s4u::Task::set_parallelism_degree(int n, std::string instance)
+
+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::get_token_from(TaskPtr t) const
+ .. doxygenfunction:: simgrid::s4u::Task::get_tokens_from(TaskPtr t) const
+ .. doxygenfunction:: simgrid::s4u::Task::deque_token_from(TaskPtr t)
+ .. doxygenfunction:: simgrid::s4u::Task::set_token(std::shared_ptr<Token> token)
+
+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::CommTask::get_source() const
+ .. doxygenfunction:: simgrid::s4u::CommTask::get_destination() const
+ .. doxygenfunction:: simgrid::s4u::CommTask::get_bytes() const
+ .. doxygenfunction:: simgrid::s4u::CommTask::set_source(Host* source);
+ .. doxygenfunction:: simgrid::s4u::CommTask::set_destination(Host* destination);
+ .. doxygenfunction:: simgrid::s4u::CommTask::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::ExecTask::get_host(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::ExecTask::get_flops(std::string instance) const
+ .. doxygenfunction:: simgrid::s4u::ExecTask::set_host(Host* host, std::string instance);
+ .. doxygenfunction:: simgrid::s4u::ExecTask::set_flops(double flops, std::string instance);
+ .. doxygenfunction:: simgrid::s4u::ExecTask::add_instances(int n);
+ .. doxygenfunction:: simgrid::s4u::ExecTask::remove_instances(int n);
+
+.. _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::IoTask::get_disk() const
+ .. doxygenfunction:: simgrid::s4u::IoTask::get_bytes() const
+ .. doxygenfunction:: simgrid::s4u::IoTask::get_op_type() const
+ .. doxygenfunction:: simgrid::s4u::IoTask::set_disk(Disk* disk);
+ .. doxygenfunction:: simgrid::s4u::IoTask::set_bytes(double bytes);
+ .. doxygenfunction:: simgrid::s4u::IoTask::set_op_type(Io::OpType type);
.. _API_s4u_Synchronizations:
.. doxygentypedef:: MutexPtr
- .. doxygenfunction:: simgrid::s4u::Mutex::create()
+ .. doxygenfunction:: simgrid::s4u::Mutex::create
.. group-tab:: Python
.. doxygenfunction:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
.. doxygenfunction:: simgrid::s4u::Barrier::wait()
+ .. doxygenfunction:: simgrid::s4u::Barrier::to_string()
.. group-tab:: Python
.. 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 />
