X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/268f33a4d5bc5c8eca704ce3028e4e3c283fdb02..a6e488781dadd92ea13e74150074c4207fefe478:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 5dd5358ca3..1395b79f3a 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 ************* @@ -399,7 +396,7 @@ Simulation objects .. group-tab:: Python - + .. autoclass:: simgrid.Actor Basic management @@ -598,7 +595,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 @@ -702,6 +699,7 @@ Logging messages .. autofunction:: simgrid.this_actor.debug .. autofunction:: simgrid.this_actor.info + .. autofunction:: simgrid.this_actor.warning .. autofunction:: simgrid.this_actor.error Sleeping @@ -742,9 +740,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 @@ -790,7 +790,7 @@ Exiting .. doxygenclass:: simgrid::s4u::Engine .. group-tab:: Python - + .. autoclass:: simgrid.Engine Engin initialization @@ -906,6 +906,7 @@ Retrieving hosts .. group-tab:: Python .. autoattribute:: simgrid.Engine.all_hosts + .. automethod:: simgrid.Engine.host_by_name .. group-tab:: C @@ -975,7 +976,7 @@ Signals .. doxygenclass:: simgrid::s4u::Mailbox .. group-tab:: Python - + .. autoclass:: simgrid.Mailbox Please also refer to the :ref:`full doc on s4u::Mailbox `. @@ -1048,6 +1049,7 @@ Sending data .. automethod:: simgrid.Mailbox.put .. automethod:: simgrid.Mailbox.put_async + .. automethod:: simgrid.Mailbox.put_init .. group-tab:: C @@ -1077,6 +1079,7 @@ Receiving data .. automethod:: simgrid.Mailbox.get .. automethod:: simgrid.Mailbox.get_async + .. autoattribute:: simgrid.Mailbox.ready .. group-tab:: C @@ -1120,7 +1123,7 @@ Resources .. doxygenclass:: simgrid::s4u::Disk .. group-tab:: Python - + .. autoclass:: simgrid.Disk .. group-tab:: C @@ -1169,7 +1172,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 @@ -1221,7 +1224,7 @@ Signals .. doxygenclass:: simgrid::s4u::Host .. group-tab:: Python - + .. autoclass:: simgrid.Host Basic management @@ -1296,11 +1299,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 @@ -1323,7 +1327,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 @@ -1392,9 +1395,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++ @@ -1406,6 +1413,7 @@ DVFS .. group-tab:: Python + .. autoattribute:: simgrid.Host.pstate .. autoattribute:: simgrid.Host.pstate_count .. automethod:: simgrid.Host.pstate_speed @@ -1464,7 +1472,7 @@ using :cpp:func:`Comm::sendto() `. .. autoattribute:: simgrid.Host.netpoint .. automethod:: simgrid.Host.create_disk - + .. automethod:: simgrid.Host.route_to .. group-tab:: C @@ -1502,7 +1510,7 @@ Signals .. group-tab:: Python - + .. autoclass:: simgrid.Link Basic management @@ -1604,7 +1612,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 @@ -1712,7 +1720,7 @@ Signals .. doxygenclass:: simgrid::s4u::NetZone .. group-tab:: Python - + .. autoclass:: simgrid.NetZone Basic management @@ -1863,16 +1871,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 @@ -2120,6 +2128,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: ============= @@ -2133,7 +2152,7 @@ Suspending and resuming an activity .. doxygenclass:: simgrid::s4u::Comm .. group-tab:: Python - + .. autoclass:: simgrid.Comm Basic management @@ -2183,11 +2202,22 @@ Querying info .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size) .. doxygenfunction:: simgrid::s4u::Comm::set_src_data_size(size_t size) -Life cycle ----------- + .. 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 + +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:: @@ -2198,6 +2228,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 @@ -2208,15 +2251,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 @@ -2250,7 +2299,7 @@ Signals .. doxygenclass:: simgrid::s4u::Exec .. group-tab:: Python - + .. autoclass:: simgrid.Exec Basic management @@ -2369,7 +2418,7 @@ Signals .. doxygenclass:: simgrid::s4u::Io .. group-tab:: Python - + .. autoclass:: simgrid.Io Basic management @@ -2407,8 +2456,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 @@ -2439,7 +2488,15 @@ Synchronization Objects ⁣  Mutex ============== -.. doxygenclass:: simgrid::s4u::Mutex +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::Mutex + + .. group-tab:: Python + + .. autoclass:: simgrid.Mutex Basic management ---------------- @@ -2456,6 +2513,21 @@ Basic management .. doxygenfunction:: simgrid::s4u::Mutex::create() + .. group-tab:: Python + + .. code-block:: Python + + 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 @@ -2481,6 +2553,12 @@ Locking .. doxygenfunction:: simgrid::s4u::Mutex::try_lock() .. doxygenfunction:: simgrid::s4u::Mutex::unlock() + .. group-tab:: Python + + .. automethod:: simgrid.Mutex.lock + .. automethod:: simgrid.Mutex.try_lock + .. automethod:: simgrid.Mutex.unlock + .. group-tab:: C .. doxygenfunction:: sg_mutex_lock(sg_mutex_t mutex) @@ -2493,7 +2571,15 @@ Locking ⁣  Barrier ================ -.. doxygenclass:: simgrid::s4u::Barrier +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::Barrier + + .. group-tab:: Python + + .. autoclass:: simgrid.Barrier .. tabs:: @@ -2505,10 +2591,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 @@ -2590,8 +2685,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 ---------------- @@ -2607,6 +2709,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 @@ -2634,6 +2749,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) @@ -2642,6 +2765,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