X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/aad6b6c4c7b1454dd284f822ba6f52e790f42c6e..6ae42d54959fc08bb83d5db2cd1aca93dfebc66f:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 5408491ea1..a44f8a199e 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -96,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 @@ -187,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 @@ -367,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 ************* @@ -396,7 +430,7 @@ Simulation objects .. group-tab:: Python - + .. autoclass:: simgrid.Actor Basic management @@ -616,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: @@ -790,7 +831,7 @@ Exiting .. doxygenclass:: simgrid::s4u::Engine .. group-tab:: Python - + .. autoclass:: simgrid.Engine Engin initialization @@ -829,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) @@ -976,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 `. @@ -1123,7 +1165,7 @@ Resources .. doxygenclass:: simgrid::s4u::Disk .. group-tab:: Python - + .. autoclass:: simgrid.Disk .. group-tab:: C @@ -1208,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: @@ -1224,7 +1268,7 @@ Signals .. doxygenclass:: simgrid::s4u::Host .. group-tab:: Python - + .. autoclass:: simgrid.Host Basic management @@ -1395,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++ @@ -1468,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 @@ -1487,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: @@ -1506,7 +1558,7 @@ Signals .. group-tab:: Python - + .. autoclass:: simgrid.Link Basic management @@ -1582,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 @@ -1698,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: @@ -1716,7 +1772,7 @@ Signals .. doxygenclass:: simgrid::s4u::NetZone .. group-tab:: Python - + .. autoclass:: simgrid.NetZone Basic management @@ -2044,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: @@ -2090,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) @@ -2124,17 +2188,6 @@ 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: ============= @@ -2148,7 +2201,7 @@ Signals .. doxygenclass:: simgrid::s4u::Comm .. group-tab:: Python - + .. autoclass:: simgrid.Comm Basic management @@ -2208,11 +2261,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:: @@ -2223,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 @@ -2237,10 +2304,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 @@ -2260,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 ------- @@ -2268,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: @@ -2285,7 +2370,7 @@ Signals .. doxygenclass:: simgrid::s4u::Exec .. group-tab:: Python - + .. autoclass:: simgrid.Exec Basic management @@ -2381,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 ------- @@ -2389,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: @@ -2404,7 +2512,7 @@ Signals .. doxygenclass:: simgrid::s4u::Io .. group-tab:: Python - + .. autoclass:: simgrid.Io Basic management @@ -2460,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: @@ -2751,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