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
*************
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:
.. group-tab:: Python
+ .. autofunction:: simgrid.this_actor.exec_async
.. autofunction:: simgrid.this_actor.exec_init
.. autofunction:: simgrid.this_actor.execute
.. 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)
.. group-tab:: Python
.. autoattribute:: simgrid.Engine.all_hosts
- .. automethod:: simgrid::s4u::Engine::host_by_name
+ .. automethod:: simgrid.Engine.host_by_name
.. group-tab:: C
.. 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::get_read_bandwidth() const
.. doxygenfunction:: simgrid::s4u::Disk::get_write_bandwidth() const
.. doxygenfunction:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value)
- .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy(Operation op, SharingPolicy policy, const s4u::NonLinearResourceCb& cb = {})
+ .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy
.. group-tab:: Python
.. 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:: simgrid::s4u::Host::set_core_count(int core_count)
.. doxygenfunction:: simgrid::s4u::Host::set_coordinates(const std::string& coords)
- .. doxygenfunction:: simgrid::s4u::Host::set_sharing_policy(SharingPolicy policy, const s4u::NonLinearResourceCb& cb = {})
+ .. doxygenfunction:: simgrid::s4u::Host::set_sharing_policy
.. group-tab:: Python
.. autoattribute:: simgrid.Host.core_count
+ :noindex:
.. automethod:: simgrid.Host.set_coordinates
.. automethod:: simgrid.Host.set_sharing_policy
.. autoattribute:: simgrid.Host.name
.. autoattribute:: simgrid.Host.core_count
.. autoattribute:: simgrid.Host.load
- .. autoattribute:: simgrid.Host.pstate
.. autoattribute:: simgrid.Host.speed
.. autoattribute:: simgrid.Host.available_speed
.. 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++
.. group-tab:: Python
+ .. autoattribute:: simgrid.Host.pstate
.. autoattribute:: simgrid.Host.pstate_count
.. automethod:: simgrid.Host.pstate_speed
.. 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
.. doxygenfunction:: simgrid::s4u::Link::set_latency(double value)
.. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value)
.. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
- .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy(SharingPolicy policy, const NonLinearResourceCb& cb = {})
+ .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
.. 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
.. group-tab:: C++
- .. doxygenfunction:: simgrid::s4u::create_full_zone(const std::string& name)
- .. doxygenfunction:: simgrid::s4u::create_empty_zone(const std::string& name)
- .. doxygenfunction:: simgrid::s4u::create_star_zone(const std::string& name)
- .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone(const std::string& name, bool cache)
- .. doxygenfunction:: simgrid::s4u::create_floyd_zone(const std::string& name)
- .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone(const std::string& name)
- .. doxygenfunction:: simgrid::s4u::create_wifi_zone(const std::string& name)
+ .. doxygenfunction:: simgrid::s4u::create_full_zone
+ .. doxygenfunction:: simgrid::s4u::create_empty_zone
+ .. doxygenfunction:: simgrid::s4u::create_star_zone
+ .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone
+ .. doxygenfunction:: simgrid::s4u::create_floyd_zone
+ .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone
+ .. doxygenfunction:: simgrid::s4u::create_wifi_zone
.. doxygenfunction:: simgrid::s4u::create_torus_zone
- .. doxygenfunction:: simgrid::s4u::create_fatTree_zone(const std::string& name, const NetZone* parent, const FatTreeParams& parameters, const ClusterCallbacks& set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
- .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone(const std::string& name, const NetZone* parent, const DragonflyParams& parameters, const ClusterCallbacks& set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
+ .. doxygenfunction:: simgrid::s4u::create_fatTree_zone
+ .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone
.. 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:
.. 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_suspend_cb
- .. doxygenfunction:: simgrid::s4u::Activity::on_resume_cb
-
.. _API_s4u_Comm:
=============
.. doxygenclass:: simgrid::s4u::Comm
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Comm
Basic management
.. automethod:: simgrid.Comm.detach
.. automethod:: simgrid.Comm.set_payload_size
.. automethod:: simgrid.Comm.set_rate
- .. automethod:: simgrid.Comm.detach
-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
.. 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
.. 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
-------
.. 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
+
.. _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
-------
.. doxygenfunction:: simgrid::s4u::Exec::on_start_cb
.. doxygenfunction:: simgrid::s4u::Exec::on_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
+
.. _API_s4u_Io:
===========
.. doxygenclass:: simgrid::s4u::Io
.. group-tab:: Python
-
+
.. autoclass:: simgrid.Io
Basic management
.. doxygenfunction:: simgrid::s4u::Io::on_start_cb
.. doxygenfunction:: simgrid::s4u::Io::on_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_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 />
