X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/ef8e45c12eed3865ec33faf5760ed19bb55e183a..6ae42d54959fc08bb83d5db2cd1aca93dfebc66f:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 2ff9d3a139..a44f8a199e 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 ************* @@ -99,6 +96,9 @@ provides many helper functions to simplify the code of actors. .. |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 @@ -190,13 +190,48 @@ with :cpp:func:`s4u::Comm::wait_all() `. :dedent: 2 ===================== -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() ` +function. + +The parameters of Tasks can be redefined at runtime by attaching +callbacks to the +:cpp:func:`s4u::Task::on_this_start ` +and +:cpp:func:`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 @@ -370,10 +405,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 +430,7 @@ Simulation objects .. group-tab:: Python - + .. autoclass:: simgrid.Actor Basic management @@ -598,6 +629,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 .. group-tab:: Python @@ -618,12 +650,19 @@ Signals .. 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: @@ -701,6 +740,7 @@ Logging messages .. autofunction:: simgrid.this_actor.debug .. autofunction:: simgrid.this_actor.info + .. autofunction:: simgrid.this_actor.warning .. autofunction:: simgrid.this_actor.error Sleeping @@ -741,9 +781,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 @@ -789,7 +831,7 @@ Exiting .. doxygenclass:: simgrid::s4u::Engine .. group-tab:: Python - + .. autoclass:: simgrid.Engine Engin initialization @@ -828,6 +870,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) @@ -905,6 +948,7 @@ Retrieving hosts .. group-tab:: Python .. autoattribute:: simgrid.Engine.all_hosts + .. automethod:: simgrid.Engine.host_by_name .. group-tab:: C @@ -974,7 +1018,7 @@ Signals .. doxygenclass:: simgrid::s4u::Mailbox .. group-tab:: Python - + .. autoclass:: simgrid.Mailbox Please also refer to the :ref:`full doc on s4u::Mailbox `. @@ -1047,6 +1091,7 @@ Sending data .. automethod:: simgrid.Mailbox.put .. automethod:: simgrid.Mailbox.put_async + .. automethod:: simgrid.Mailbox.put_init .. group-tab:: C @@ -1068,7 +1113,7 @@ Receiving data .. doxygenfunction:: simgrid::s4u::Mailbox::get(double timeout) .. doxygenfunction:: simgrid::s4u::Mailbox::get_async(T **data) .. doxygenfunction:: simgrid::s4u::Mailbox::get_init() - .. doxygenfunction:: simgrid::s4u::Mailbox::iprobe(int type, bool(*match_fun)(void *, void *, kernel::activity::CommImpl *), void *data) + .. doxygenfunction:: simgrid::s4u::Mailbox::iprobe(int type, const std::function& match_fun, void *data) .. doxygenfunction:: simgrid::s4u::Mailbox::listen .. doxygenfunction:: simgrid::s4u::Mailbox::ready @@ -1076,6 +1121,7 @@ Receiving data .. automethod:: simgrid.Mailbox.get .. automethod:: simgrid.Mailbox.get_async + .. autoattribute:: simgrid.Mailbox.ready .. group-tab:: C @@ -1119,7 +1165,7 @@ Resources .. doxygenclass:: simgrid::s4u::Disk .. group-tab:: Python - + .. autoclass:: simgrid.Disk .. group-tab:: C @@ -1168,7 +1214,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 @@ -1204,7 +1250,9 @@ Signals .. 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: @@ -1220,7 +1268,7 @@ Signals .. doxygenclass:: simgrid::s4u::Host .. group-tab:: Python - + .. autoclass:: simgrid.Host Basic management @@ -1295,11 +1343,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 @@ -1322,7 +1371,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 @@ -1391,9 +1439,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++ @@ -1405,6 +1457,7 @@ DVFS .. group-tab:: Python + .. autoattribute:: simgrid.Host.pstate .. autoattribute:: simgrid.Host.pstate_count .. automethod:: simgrid.Host.pstate_speed @@ -1463,7 +1516,7 @@ using :cpp:func:`Comm::sendto() `. .. autoattribute:: simgrid.Host.netpoint .. automethod:: simgrid.Host.create_disk - + .. automethod:: simgrid.Host.route_to .. group-tab:: C @@ -1482,8 +1535,12 @@ Signals .. 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: @@ -1501,7 +1558,7 @@ Signals .. group-tab:: Python - + .. autoclass:: simgrid.Link Basic management @@ -1577,6 +1634,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 @@ -1603,7 +1661,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 @@ -1693,10 +1751,13 @@ Signals .. 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: @@ -1711,7 +1772,7 @@ Signals .. doxygenclass:: simgrid::s4u::NetZone .. group-tab:: Python - + .. autoclass:: simgrid.NetZone Basic management @@ -1862,16 +1923,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 @@ -2039,13 +2100,21 @@ Signals .. 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: @@ -2085,8 +2154,8 @@ 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) @@ -2132,7 +2201,7 @@ Suspending and resuming an activity .. doxygenclass:: simgrid::s4u::Comm .. group-tab:: Python - + .. autoclass:: simgrid.Comm Basic management @@ -2161,7 +2230,6 @@ Basic management #include .. doxygentypedef:: sg_comm_t - .. doxygentypedef:: const_sg_comm_t Querying info ------------- @@ -2176,18 +2244,29 @@ Querying info .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff) .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size) .. doxygenfunction:: simgrid::s4u::Comm::detach() - .. doxygenfunction:: simgrid::s4u::Comm::detach(void(*clean_function)(void *)) + .. doxygenfunction:: simgrid::s4u::Comm::detach(const std::function& clean_function) .. doxygenfunction:: simgrid::s4u::Comm::set_payload_size(uint64_t bytes) .. doxygenfunction:: simgrid::s4u::Comm::set_rate(double rate) .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff) .. 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 +2277,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,13 +2300,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 @@ -2223,6 +2323,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 ------- @@ -2231,9 +2348,14 @@ Signals .. group-tab:: C++ .. doxygenfunction:: simgrid::s4u::Comm::on_start_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_this_start_cb .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_this_completion_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_resumed_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_veto_cb .. _API_s4u_Exec: @@ -2248,7 +2370,7 @@ Signals .. doxygenclass:: simgrid::s4u::Exec .. group-tab:: Python - + .. autoclass:: simgrid.Exec Basic management @@ -2344,6 +2466,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 ------- @@ -2352,7 +2491,13 @@ 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 .. _API_s4u_Io: @@ -2367,7 +2512,7 @@ Signals .. doxygenclass:: simgrid::s4u::Io .. group-tab:: Python - + .. autoclass:: simgrid.Io Basic management @@ -2405,8 +2550,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 @@ -2423,7 +2568,210 @@ 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 + + +.. _API_s4u_Tasks: + +========== +Tasks +========== + +============== +class Task +============== + +.. doxygenclass:: simgrid::s4u::Task + +**Known subclasses:** +:ref:`Communication Tasks `, +:ref:`Executions Tasks `, +:ref:`I/O Tasks `. +See also the :ref:`section on activities ` above. + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. 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() const + .. doxygenfunction:: simgrid::s4u::Task::get_amount() const + .. doxygenfunction:: simgrid::s4u::Task::set_amount(double amount) + +Life cycle +---------- + +.. tabs:: + + .. group-tab:: C++ + .. doxygenfunction:: simgrid::s4u::Task::enqueue_firings(int n) + +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::set_token(std::shared_ptr token) + .. doxygenfunction:: simgrid::s4u::Task::get_next_token_from(TaskPtr t) + +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 + + .. doxygentypedef:: CommTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_source() const + .. doxygenfunction:: simgrid::s4u::Task::get_destination() const + .. doxygenfunction:: simgrid::s4u::Task::get_bytes() const + .. doxygenfunction:: simgrid::s4u::Task::set_source(simgrid::s4u::Host* source); + .. doxygenfunction:: simgrid::s4u::Task::set_destination(simgrid::s4u::Host* destination); + .. doxygenfunction:: simgrid::s4u::Task::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 + + .. doxygentypedef:: ExecTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_host() const + .. doxygenfunction:: simgrid::s4u::Task::get_flops() const + .. doxygenfunction:: simgrid::s4u::Task::set_host(simgrid::s4u::Host* host); + .. doxygenfunction:: simgrid::s4u::Task::set_flops(double flops); + +.. _API_s4u_IoTask: + +================ +⁣  class IoTask +================ +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::IoTask + +Basic management +---------------- + +.. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: IoTaskPtr + +Querying info +------------- + +.. tabs:: + + .. group-tab:: C++ + + .. doxygenfunction:: simgrid::s4u::Task::get_disk() const + .. doxygenfunction:: simgrid::s4u::Task::get_bytes() const + .. doxygenfunction:: simgrid::s4u::Task::get_op_type() const + .. doxygenfunction:: simgrid::s4u::Task::set_disk(simgrid::s4u::Disk* disk); + .. doxygenfunction:: simgrid::s4u::Task::set_bytes(simgrid::double bytes); + .. doxygenfunction:: simgrid::s4u::Task::set_op_type(simgrid::s4u::Io::OpType type); .. _API_s4u_Synchronizations: @@ -2437,7 +2785,15 @@ Synchronization Objects ⁣  Mutex ============== -.. doxygenclass:: simgrid::s4u::Mutex +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::Mutex + + .. group-tab:: Python + + .. autoclass:: simgrid.Mutex Basic management ---------------- @@ -2454,6 +2810,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 @@ -2479,6 +2850,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) @@ -2491,7 +2868,15 @@ Locking ⁣  Barrier ================ -.. doxygenclass:: simgrid::s4u::Barrier +.. tabs:: + + .. group-tab:: C++ + + .. doxygenclass:: simgrid::s4u::Barrier + + .. group-tab:: Python + + .. autoclass:: simgrid.Barrier .. tabs:: @@ -2503,10 +2888,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 @@ -2514,10 +2908,9 @@ Locking #include .. doxygentypedef:: sg_bar_t - .. doxygentypedef:: const_sg_bar_t .. doxygenfunction:: sg_barrier_init(unsigned int count) - .. doxygenfunction:: sg_barrier_destroy(const_sg_bar_t bar) + .. doxygenfunction:: sg_barrier_destroy(sg_bar_t bar) .. doxygenfunction:: sg_barrier_wait(sg_bar_t bar) @@ -2589,8 +2982,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 ---------------- @@ -2606,6 +3006,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 @@ -2633,6 +3046,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) @@ -2641,6 +3062,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