X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/472cf2ae0b7d14830217c5a0024c5c27c2336af4..458916c04f29576ae5949d7a395c4ed686f2e8b9:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 014a1e96ed..7d3d6b0767 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -20,15 +20,12 @@ with the full power of C++. This is the preferred interface to describe 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 ` 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 ************* @@ -370,10 +367,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 ************* @@ -399,7 +392,7 @@ Simulation objects .. group-tab:: Python - + .. autoclass:: simgrid.Actor Basic management @@ -793,7 +786,7 @@ Exiting .. doxygenclass:: simgrid::s4u::Engine .. group-tab:: Python - + .. autoclass:: simgrid.Engine Engin initialization @@ -832,6 +825,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) @@ -979,7 +973,7 @@ Signals .. doxygenclass:: simgrid::s4u::Mailbox .. group-tab:: Python - + .. autoclass:: simgrid.Mailbox Please also refer to the :ref:`full doc on s4u::Mailbox `. @@ -1126,7 +1120,7 @@ Resources .. doxygenclass:: simgrid::s4u::Disk .. group-tab:: Python - + .. autoclass:: simgrid.Disk .. group-tab:: C @@ -1227,7 +1221,7 @@ Signals .. doxygenclass:: simgrid::s4u::Host .. group-tab:: Python - + .. autoclass:: simgrid.Host Basic management @@ -1398,9 +1392,13 @@ On/Off .. 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 `. + .. tabs:: .. group-tab:: C++ @@ -1471,7 +1469,7 @@ using :cpp:func:`Comm::sendto() `. .. autoattribute:: simgrid.Host.netpoint .. automethod:: simgrid.Host.create_disk - + .. automethod:: simgrid.Host.route_to .. group-tab:: C @@ -1509,7 +1507,7 @@ Signals .. group-tab:: Python - + .. autoclass:: simgrid.Link Basic management @@ -1585,6 +1583,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 @@ -1719,7 +1718,7 @@ Signals .. doxygenclass:: simgrid::s4u::NetZone .. group-tab:: Python - + .. autoclass:: simgrid.NetZone Basic management @@ -2151,7 +2150,7 @@ Signals .. doxygenclass:: simgrid::s4u::Comm .. group-tab:: Python - + .. autoclass:: simgrid.Comm Basic management @@ -2211,11 +2210,12 @@ Querying info .. 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 `. .. tabs:: @@ -2226,6 +2226,19 @@ also start direct communications as shown below. .. 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 @@ -2240,10 +2253,6 @@ also start direct communications as shown below. .. 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 @@ -2263,6 +2272,23 @@ also start direct communications as shown below. .. 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 ------- @@ -2288,7 +2314,7 @@ Signals .. doxygenclass:: simgrid::s4u::Exec .. group-tab:: Python - + .. autoclass:: simgrid.Exec Basic management @@ -2384,6 +2410,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 ------- @@ -2407,7 +2450,7 @@ Signals .. doxygenclass:: simgrid::s4u::Io .. group-tab:: Python - + .. autoclass:: simgrid.Io Basic management @@ -2754,6 +2797,55 @@ Locking .. 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