X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/25640a21a7ea2b5283d7db306491d770ff87b81c..5a006fa396cfcc8a91a8284f0d625b2a9a2565c9:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 7f9b1ae1d5..e5c5e71140 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 @@ -598,7 +591,7 @@ Reacting to the end of actors .. doxygenfunction:: simgrid::s4u::Actor::join() const .. doxygenfunction:: simgrid::s4u::Actor::join(double timeout) const .. doxygenfunction:: simgrid::s4u::Actor::set_auto_restart(bool autorestart) - .. doxygenfunction:: simgrid::s4u::Actor::get_restart_count() + .. doxygenfunction:: simgrid::s4u::Actor::get_restart_count .. group-tab:: Python @@ -743,9 +736,11 @@ the execution, or start an asynchronous activity. .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop) .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop, double priority) .. doxygenfunction:: simgrid::s4u::this_actor::parallel_execute(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts) + .. doxygenfunction:: simgrid::s4u::this_actor::thread_execute .. group-tab:: Python + .. autofunction:: simgrid.this_actor.exec_async .. autofunction:: simgrid.this_actor.exec_init .. autofunction:: simgrid.this_actor.execute @@ -791,7 +786,7 @@ Exiting .. doxygenclass:: simgrid::s4u::Engine .. group-tab:: Python - + .. autoclass:: simgrid.Engine Engin initialization @@ -907,6 +902,7 @@ Retrieving hosts .. group-tab:: Python .. autoattribute:: simgrid.Engine.all_hosts + .. automethod:: simgrid.Engine.host_by_name .. group-tab:: C @@ -976,7 +972,7 @@ Signals .. doxygenclass:: simgrid::s4u::Mailbox .. group-tab:: Python - + .. autoclass:: simgrid.Mailbox Please also refer to the :ref:`full doc on s4u::Mailbox `. @@ -1079,6 +1075,7 @@ Receiving data .. automethod:: simgrid.Mailbox.get .. automethod:: simgrid.Mailbox.get_async + .. autoattribute:: simgrid.Mailbox.ready .. group-tab:: C @@ -1122,7 +1119,7 @@ Resources .. doxygenclass:: simgrid::s4u::Disk .. group-tab:: Python - + .. autoclass:: simgrid.Disk .. group-tab:: C @@ -1171,7 +1168,7 @@ Querying info .. 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 @@ -1223,7 +1220,7 @@ Signals .. doxygenclass:: simgrid::s4u::Host .. group-tab:: Python - + .. autoclass:: simgrid.Host Basic management @@ -1298,11 +1295,12 @@ Modifying characteristics .. 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 @@ -1325,7 +1323,6 @@ Querying info .. 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 @@ -1394,9 +1391,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++ @@ -1408,6 +1409,7 @@ DVFS .. group-tab:: Python + .. autoattribute:: simgrid.Host.pstate .. autoattribute:: simgrid.Host.pstate_count .. automethod:: simgrid.Host.pstate_speed @@ -1466,7 +1468,7 @@ using :cpp:func:`Comm::sendto() `. .. autoattribute:: simgrid.Host.netpoint .. automethod:: simgrid.Host.create_disk - + .. automethod:: simgrid.Host.route_to .. group-tab:: C @@ -1504,7 +1506,7 @@ Signals .. group-tab:: Python - + .. autoclass:: simgrid.Link Basic management @@ -1606,7 +1608,7 @@ Modifying characteristics .. 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 @@ -1714,7 +1716,7 @@ Signals .. doxygenclass:: simgrid::s4u::NetZone .. group-tab:: Python - + .. autoclass:: simgrid.NetZone Basic management @@ -1865,16 +1867,16 @@ Zones .. 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 @@ -2122,6 +2124,17 @@ 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: ============= @@ -2135,7 +2148,7 @@ Suspending and resuming an activity .. doxygenclass:: simgrid::s4u::Comm .. group-tab:: Python - + .. autoclass:: simgrid.Comm Basic management @@ -2187,13 +2200,20 @@ Querying info .. group-tab:: Python + .. autoattribute:: simgrid.Comm.dst_data_size + .. autoattribute:: simgrid.Comm.mailbox + .. autoattribute:: simgrid.Comm.sender + .. autoattribute:: simgrid.Comm.state_str .. automethod:: simgrid.Comm.detach + .. 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:: @@ -2204,6 +2224,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 @@ -2214,16 +2247,21 @@ also start direct communications as shown below. .. 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.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 @@ -2232,6 +2270,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 ------- @@ -2257,7 +2312,7 @@ Signals .. doxygenclass:: simgrid::s4u::Exec .. group-tab:: Python - + .. autoclass:: simgrid.Exec Basic management @@ -2353,6 +2408,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 ------- @@ -2376,7 +2448,7 @@ Signals .. doxygenclass:: simgrid::s4u::Io .. group-tab:: Python - + .. autoclass:: simgrid.Io Basic management @@ -2414,8 +2486,8 @@ Life cycle .. doxygenfunction:: simgrid::s4u::Io::test .. doxygenfunction:: simgrid::s4u::Io::wait .. doxygenfunction:: simgrid::s4u::Io::wait_for - .. doxygenfunction:: simgrid::s4u::Io::wait_any - .. doxygenfunction:: simgrid::s4u::Io::wait_any_for + .. doxygenfunction:: simgrid::s4u::Io::wait_any(const std::vector &ios) + .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector &ios, double timeout) .. group-tab:: Python @@ -2478,6 +2550,14 @@ Basic management from simgrid import Mutex mutex = Mutex() + # Use a context manager to acquire and automatically release the mutex + # when leaving the scope. + with mutex: + # Access shared resource ... + pass + + .. automethod:: simgrid.Mutex.__init__ + .. group-tab:: C .. code-block:: C @@ -2505,9 +2585,9 @@ Locking .. group-tab:: Python - .. automethod:: simgrid.Mutex.lock() - .. automethod:: simgrid.Mutex.try_lock() - .. automethod:: simgrid.Mutex.unlock() + .. automethod:: simgrid.Mutex.lock + .. automethod:: simgrid.Mutex.try_lock + .. automethod:: simgrid.Mutex.unlock .. group-tab:: C @@ -2521,7 +2601,15 @@ Locking ⁣  Barrier ================ -.. doxygenclass:: simgrid::s4u::Barrier +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::Barrier + + .. group-tab:: Python + + .. autoclass:: simgrid.Barrier .. tabs:: @@ -2533,10 +2621,19 @@ Locking .. doxygentypedef:: BarrierPtr - .. doxygenfunction:: simgrid::s4u::Barrier::Barrier(unsigned int expected_actors) .. doxygenfunction:: simgrid::s4u::Barrier::create(unsigned int expected_actors) .. doxygenfunction:: simgrid::s4u::Barrier::wait() + .. group-tab:: Python + + .. code-block:: Python + + from simgrid import Barrier + barrier = Barrier(2) + + .. automethod:: simgrid.Barrier.__init__ + .. automethod:: simgrid.Barrier.wait + .. group-tab:: C .. code-block:: C @@ -2618,8 +2715,15 @@ Waiting and notifying ⁣  Semaphore ================== -.. doxygenclass:: simgrid::s4u::Semaphore +.. tabs:: + + .. group-tab:: C++ + .. doxygenclass:: simgrid::s4u::Semaphore + + .. group-tab:: Python + + .. autoclass:: simgrid.Semaphore Basic management ---------------- @@ -2635,6 +2739,19 @@ Basic management .. doxygentypedef:: SemaphorePtr .. doxygenfunction:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity) + .. group-tab:: Python + + .. code-block:: Python + + from simgrid import Semaphore + semaphore = Semaphore(1) + # Automatically acquire the semaphore, and release it after leaving the scope. + with semaphore: + # Do something with the shared resource + pass + + .. automethod:: simgrid.Semaphore.__init__ + .. group-tab:: C .. code-block:: C @@ -2662,6 +2779,14 @@ Locking .. doxygenfunction:: simgrid::s4u::Semaphore::release() .. doxygenfunction:: simgrid::s4u::Semaphore::would_block() const + .. group-tab:: Python + + .. automethod:: simgrid.Semaphore.acquire + .. automethod:: simgrid.Semaphore.acquire_timeout + .. autoattribute:: simgrid.Semaphore.capacity + .. automethod:: simgrid.Semaphore.release + .. autoattribute:: simgrid.Semaphore.would_block + .. group-tab:: C .. doxygenfunction:: sg_sem_acquire(sg_sem_t sem) @@ -2670,6 +2795,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