From: Martin Quinson Date: Sat, 22 Jan 2022 13:44:51 +0000 (+0100) Subject: Many tiny documentation improvements X-Git-Tag: v3.30~59 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/15178c7908a80843a430025313d143b7cb52d06a Many tiny documentation improvements - Fix links now that signals are hidden but *_cb functions provided - Add some links from functions to examples - Reference some previously unreferenced examples - Fix some Doxygen errors --- diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst index dc475e5c00..08c454eb1d 100644 --- a/docs/source/Plugins.rst +++ b/docs/source/Plugins.rst @@ -69,48 +69,48 @@ kind of objects, please let us now. Partial list of existing signals in s4u: -- :cpp:member:`Actor::on_creation ` - :cpp:member:`Actor::on_suspend ` - :cpp:member:`Actor::on_resume ` - :cpp:member:`Actor::on_sleep ` - :cpp:member:`Actor::on_wake_up ` - :cpp:member:`Actor::on_host_change ` - :cpp:member:`Actor::on_termination ` - :cpp:member:`Actor::on_destruction ` -- :cpp:member:`Comm::on_send ` - :cpp:member:`Comm::on_recv ` - :cpp:member:`Comm::on_completion ` -- :cpp:member:`CommImpl::on_start ` - :cpp:member:`CommImpl::on_completion ` -- :cpp:member:`Disk::on_creation ` - :cpp:member:`Disk::on_destruction ` - :cpp:member:`Disk::on_state_change ` -- :cpp:member:`Engine::on_platform_creation ` - :cpp:member:`Engine::on_platform_created ` - :cpp:member:`Engine::on_time_advance ` - :cpp:member:`Engine::on_simulation_end ` - :cpp:member:`Engine::on_deadlock ` -- :cpp:member:`Exec::on_start ` - :cpp:member:`Exec::on_completion ` -- :cpp:member:`Host::on_creation ` - :cpp:member:`Host::on_destruction ` - :cpp:member:`Host::on_state_change ` - :cpp:member:`Host::on_speed_change ` -- :cpp:member:`Io::on_start ` - :cpp:member:`Io::on_completion ` -- :cpp:member:`Link::on_creation ` - :cpp:member:`Link::on_destruction ` - :cpp:member:`Link::on_state_change ` - :cpp:member:`Link::on_speed_change ` - :cpp:member:`Link::on_communication_state_change ` -- :cpp:member:`NetZone::on_creation ` - :cpp:member:`NetZone::on_seal ` -- :cpp:member:`VirtualMachine::on_start ` - :cpp:member:`VirtualMachine::on_started ` - :cpp:member:`VirtualMachine::on_suspend ` - :cpp:member:`VirtualMachine::on_resume ` - :cpp:member:`VirtualMachine::on_migration_start ` - :cpp:member:`VirtualMachine::on_migration_end ` +- :cpp:member:`Actor::on_creation ` + :cpp:member:`Actor::on_suspend ` + :cpp:member:`Actor::on_resume ` + :cpp:member:`Actor::on_sleep ` + :cpp:member:`Actor::on_wake_up ` + :cpp:member:`Actor::on_host_change ` + :cpp:member:`Actor::on_termination ` + :cpp:member:`Actor::on_destruction ` +- :cpp:member:`Comm::on_send ` + :cpp:member:`Comm::on_recv ` + :cpp:member:`Comm::on_completion ` +- :cpp:member:`CommImpl::on_start ` + :cpp:member:`CommImpl::on_completion ` +- :cpp:member:`Disk::on_creation ` + :cpp:member:`Disk::on_destruction ` + :cpp:member:`Disk::on_state_change ` +- :cpp:member:`Engine::on_platform_creation ` + :cpp:member:`Engine::on_platform_created ` + :cpp:member:`Engine::on_time_advance ` + :cpp:member:`Engine::on_simulation_end ` + :cpp:member:`Engine::on_deadlock ` +- :cpp:member:`Exec::on_start ` + :cpp:member:`Exec::on_completion ` +- :cpp:member:`Host::on_creation ` + :cpp:member:`Host::on_destruction ` + :cpp:member:`Host::on_state_change ` + :cpp:member:`Host::on_speed_change ` +- :cpp:member:`Io::on_start ` + :cpp:member:`Io::on_completion ` +- :cpp:member:`Link::on_creation ` + :cpp:member:`Link::on_destruction ` + :cpp:member:`Link::on_state_change ` + :cpp:member:`Link::on_speed_change ` + :cpp:member:`Link::on_communication_state_change ` +- :cpp:member:`NetZone::on_creation ` + :cpp:member:`NetZone::on_seal ` +- :cpp:member:`VirtualMachine::on_start ` + :cpp:member:`VirtualMachine::on_started ` + :cpp:member:`VirtualMachine::on_suspend ` + :cpp:member:`VirtualMachine::on_resume ` + :cpp:member:`VirtualMachine::on_migration_start ` + :cpp:member:`VirtualMachine::on_migration_end ` Existing Plugins **************** diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index c86574390a..b98b49a341 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -453,6 +453,8 @@ Basic management Creating actors --------------- +See also :ref:`the relevant example `. + .. tabs:: .. group-tab:: C++ @@ -958,11 +960,11 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Engine::on_deadlock - .. doxygenvariable:: simgrid::s4u::Engine::on_platform_created - .. doxygenvariable:: simgrid::s4u::Engine::on_platform_creation - .. doxygenvariable:: simgrid::s4u::Engine::on_simulation_end - .. doxygenvariable:: simgrid::s4u::Engine::on_time_advance + .. doxygenfunction:: simgrid::s4u::Engine::on_deadlock_cb + .. doxygenfunction:: simgrid::s4u::Engine::on_platform_created_cb + .. doxygenfunction:: simgrid::s4u::Engine::on_platform_creation_cb + .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_end_cb + .. doxygenfunction:: simgrid::s4u::Engine::on_time_advance_cb .. _API_s4u_Mailbox: @@ -1439,7 +1441,7 @@ using :cpp:func:`Comm::sendto() `. .. doxygenfunction:: simgrid::s4u::Host::get_englobing_zone() const .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const - .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) const + .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::StandardLinkImpl * > &links, double *latency) const .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, double read_bandwidth, double write_bandwidth) .. doxygenfunction:: simgrid::s4u::Host::create_disk(const std::string& name, const std::string& read_bandwidth, const std::string& write_bandwidth) @@ -1462,10 +1464,10 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Host::on_creation - .. doxygenvariable:: simgrid::s4u::Host::on_destruction - .. doxygenvariable:: simgrid::s4u::Host::on_speed_change - .. doxygenvariable:: simgrid::s4u::Host::on_state_change + .. doxygenfunction:: simgrid::s4u::Host::on_creation_cb + .. doxygenfunction:: simgrid::s4u::Host::on_destruction_cb + .. doxygenfunction:: simgrid::s4u::Host::on_speed_change_cb + .. doxygenfunction:: simgrid::s4u::Host::on_state_change_cb .. _API_s4u_Link: @@ -1652,11 +1654,11 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Link::on_bandwidth_change - .. doxygenvariable:: simgrid::s4u::Link::on_communication_state_change - .. doxygenvariable:: simgrid::s4u::Link::on_creation - .. doxygenvariable:: simgrid::s4u::Link::on_destruction - .. doxygenvariable:: simgrid::s4u::Link::on_state_change + .. doxygenfunction:: simgrid::s4u::Link::on_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 .. _API_s4u_NetZone: @@ -1810,8 +1812,8 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::NetZone::on_creation - .. doxygenvariable:: simgrid::s4u::NetZone::on_seal + .. doxygenfunction:: simgrid::s4u::NetZone::on_creation_cb + .. doxygenfunction:: simgrid::s4u::NetZone::on_seal_cb Creating resources ------------------ @@ -2190,9 +2192,9 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Comm::on_completion - .. doxygenvariable:: simgrid::s4u::Comm::on_recv - .. doxygenvariable:: simgrid::s4u::Comm::on_send + .. doxygenfunction:: simgrid::s4u::Comm::on_completion_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_recv_cb + .. doxygenfunction:: simgrid::s4u::Comm::on_send_cb .. _API_s4u_Exec: @@ -2310,8 +2312,8 @@ Signals .. group-tab:: C++ - .. doxygenvariable:: simgrid::s4u::Exec::on_start - .. doxygenvariable:: simgrid::s4u::Exec::on_completion + .. doxygenfunction:: simgrid::s4u::Exec::on_start_cb + .. doxygenfunction:: simgrid::s4u::Exec::on_completion_cb .. _API_s4u_Io: diff --git a/examples/README.rst b/examples/README.rst index 8b453937f6..8645aff881 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -32,6 +32,8 @@ Actors: the Active Entities Starting and Stopping Actors ---------------------------- +.. _s4u_ex_actors_create: + Creating actors ^^^^^^^^^^^^^^^ @@ -387,7 +389,7 @@ The ``wait_all()`` function is useful when you want to block until all activitie Waiting for the first completed communication in a set ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The ``wait_any()`` function is useful when you want to block until one activity of the set completes, no matter which terminates first. +The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first. .. tabs:: @@ -403,6 +405,18 @@ The ``wait_any()`` function is useful when you want to block until one activity See also :cpp:func:`sg_comm_wait_any`. +Testing whether at least one communication completed +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``test_any()`` returns whether at least one activity of the set has completed, or -1. + +.. tabs:: + + .. example-tab:: examples/cpp/comm-testany/s4u-comm-testany.cpp + + See also :cpp:func:`simgrid::s4u::Comm::test_any()`. + + .. _s4u_ex_execution: Executions on the CPU @@ -770,6 +784,17 @@ This example shows how to retrieve the amount of energy consumed by the CPU duri .. example-tab:: examples/c/energy-exec/energy-exec.c +Virtual machines consumption +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example is very similar to the previous one, adding VMs to the picture. + +.. tabs:: + + .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp + + .. example-tab:: examples/c/energy-vm/energy-vm.c + Wired network energy consumption ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1170,7 +1195,7 @@ The model-checker can be used to exhaustively search for issues in the tested ap mode is rather experimental in SimGrid (as of v3.25). We are working on it :) Failing assert -^^^^^^^^^^^^^^ +-------------- In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order. This is wrong, and the model-checker correctly finds a counter-example to that assertion. diff --git a/include/simgrid/s4u/Activity.hpp b/include/simgrid/s4u/Activity.hpp index 4319dcbb1c..639bd51849 100644 --- a/include/simgrid/s4u/Activity.hpp +++ b/include/simgrid/s4u/Activity.hpp @@ -103,7 +103,7 @@ public: /*! Add a callback fired each time that the activity fails to start because of a veto (e.g., unsolved dependency or no * resource assigned) */ static void on_veto_cb(const std::function& cb) { on_veto.connect(cb); } - /*! Add a callback fired when theactivity completes (either normally, cancelled or failed) */ + /*! Add a callback fired when the activity completes (either normally, cancelled or failed) */ static void on_completion_cb(const std::function& cb) { on_completion.connect(cb); } void vetoable_start() diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 84d93453fd..9e253158f4 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -251,8 +251,9 @@ public: * If you want to register to the termination of a given actor, use this_actor::on_exit() instead.*/ static void on_destruction_cb(const std::function& cb) { on_destruction.connect(cb); } - /** Create an actor from a std::function. - * If the actor is restarted, it gets a fresh copy of the function. */ + /** Create an actor from a @c std::function. + * If the actor is restarted, it gets a fresh copy of the function. + * @verbatim embed:rst:inline See the :ref:`example `. @endverbatim */ static ActorPtr create(const std::string& name, s4u::Host* host, const std::function& code); /** Create an actor, but don't start it yet. * @@ -277,7 +278,8 @@ public: ActorPtr start(const std::function& code, std::vector args); - /** Create an actor from a callable thing. */ + /** Create an actor from a callable thing. + * @verbatim embed:rst:inline See the :ref:`example `. @endverbatim */ template static ActorPtr create(const std::string& name, s4u::Host* host, F code) { return create(name, host, std::function(std::move(code))); @@ -285,7 +287,8 @@ public: /** Create an actor using a callable thing and its arguments. * - * Note that the arguments will be copied, so move-only parameters are forbidden */ + * Note that the arguments will be copied, so move-only parameters are forbidden. + * @verbatim embed:rst:inline See the :ref:`example `. @endverbatim */ template `. @endverbatim */ static ActorPtr create(const std::string& name, s4u::Host* host, const std::string& function, std::vector args); diff --git a/include/simgrid/s4u/Comm.hpp b/include/simgrid/s4u/Comm.hpp index b900be0624..5c746e19bf 100644 --- a/include/simgrid/s4u/Comm.hpp +++ b/include/simgrid/s4u/Comm.hpp @@ -66,7 +66,7 @@ public: static void on_send_cb(const std::function& cb) { on_send.connect(cb); } static void on_recv_cb(const std::function& cb) { on_recv.connect(cb); } static void on_start_cb(const std::function& cb) { on_start.connect(cb); } - static void on_completion_cb(const std::function& cb) { on_completion.connect(cb); } + static void on_completion_cb(const std::function& cb) { on_completion.connect(cb); } #ifndef DOXYGEN /* FIXME signals should be private */ static xbt::signal on_send; diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp index 43be0eba37..f989f396f5 100644 --- a/include/simgrid/s4u/Engine.hpp +++ b/include/simgrid/s4u/Engine.hpp @@ -60,13 +60,17 @@ public: void load_platform(const std::string& platf) const; void seal_platform() const; + /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function taking classical argc/argv parameters. See the :ref:`example `. @endverbatim */ void register_function(const std::string& name, const std::function& code); + /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function taking a vector of strings as a parameter. See the :ref:`example `. @endverbatim */ void register_function(const std::string& name, const std::function)>& code); void register_function(const std::string& name, const kernel::actor::ActorCodeFactory& factory); + /** @verbatim embed:rst:inline Provide a default function to be used when the name used in a :ref:`pf_tag_actor` tag was not binded with ``register_function`` nor ``register_actor``. @endverbatim */ void register_default(const std::function& code); void register_default(const kernel::actor::ActorCodeFactory& factory); + /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a class name passed as a template parameter. See the :ref:`example `. @endverbatim */ template void register_actor(const std::string& name) { kernel::actor::ActorCodeFactory code_factory = [](std::vector args) { @@ -77,6 +81,7 @@ public: }; register_function(name, code_factory); } + /** @verbatim embed:rst:inline Bind an actor name that could be found in :ref:`pf_tag_actor` tag to a function name passed as a parameter. See the :ref:`example `. @endverbatim */ template void register_actor(const std::string& name, F code) { kernel::actor::ActorCodeFactory code_factory = [code](std::vector args) { @@ -88,6 +93,7 @@ public: /** If non-null, the provided set will be filled with all activities that fail to start because of a veto */ void track_vetoed_activities(std::set* vetoed_activities) const; + /** @verbatim embed:rst:inline Load a deployment file. See:ref:`deploy` and the :ref:`example `. @endverbatim */ void load_deployment(const std::string& deploy) const; protected: diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp index 000ed7e3af..9ed6cc2603 100644 --- a/include/simgrid/s4u/Host.hpp +++ b/include/simgrid/s4u/Host.hpp @@ -152,13 +152,19 @@ public: /** @brief Get the peak computing speed in flops/s at the current pstate, NOT taking the external load into account. * * The amount of flops per second available for computing depends on several things: - * - The current pstate determines the maximal peak computing speed (use @ref get_pstate_speed() to retrieve the - * computing speed you would get at another pstate) - * - If you declared an external load (with @ref set_speed_profile()), you must multiply the - * result of get_speed() by get_available_speed() to retrieve what a new computation would get. + * - The current pstate determines the maximal peak computing speed (use + * @verbatim embed:rst:inline :cpp:func:`get_pstate_speed() ` @endverbatim + * to retrieve the computing speed you would get at another pstate) + * - If you declared an external load (with + * @verbatim embed:rst:inline :cpp:func:`set_speed_profile() ` + * @endverbatim ), you must multiply the result of + * @verbatim embed:rst:inline :cpp:func:`get_speed() ` @endverbatim by + * @verbatim embed:rst:inline :cpp:func:`get_available_speed() ` + * @endverbatim to retrieve what a new computation would get. * * The remaining speed is then shared between the executions located on this host. - * You can retrieve the amount of tasks currently running on this host with @ref get_load(). + * You can retrieve the amount of tasks currently running on this host with + * @verbatim embed:rst:inline :cpp:func:`get_load() ` @endverbatim . * * The host may have multiple cores, and your executions may be able to use more than a single core. * @@ -167,7 +173,8 @@ public: double get_speed() const; /** @brief Get the available speed ratio, between 0 and 1. * - * This accounts for external load (see @ref set_speed_profile()). + * This accounts for external load (see + * @verbatim embed:rst:inline :cpp:func:`set_speed_profile() ` @endverbatim ). */ double get_available_speed() const; diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h index 817b737343..8ef3368d8d 100644 --- a/include/xbt/dynar.h +++ b/include/xbt/dynar.h @@ -18,7 +18,8 @@ SG_BEGIN_DECL /** @brief Dynar data type (opaque type) * * These are the SimGrid version of the DYNamically sized ARays, which all C programmer recode one day or another. - * For performance concerns, the content of dynars must be homogeneous (in contrary to @ref xbt_dict_t). + * For performance concerns, the content of dynars must be homogeneous (in contrary to + * @verbatim embed:rst:inline :cpp:type:`xbt_dict_t` @endverbatim ). * You thus have to provide the function which will be used to free the content at * structure creation (of type void_f_pvoid_t). */ diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp index 0bf85989ee..47c669a422 100644 --- a/src/bindings/python/simgrid_python.cpp +++ b/src/bindings/python/simgrid_python.cpp @@ -502,7 +502,7 @@ PYBIND11_MODULE(simgrid, m) } }); }, - py::call_guard(), "Create an actor from a function or an object.") + py::call_guard(), "Create an actor from a function or an object. See the :ref:`example `.") .def_property( "host", &Actor::get_host, [](Actor* a, Host* h) { diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp index 17b7f43941..aa56f7783d 100644 --- a/src/s4u/s4u_Host.cpp +++ b/src/s4u/s4u_Host.cpp @@ -28,10 +28,12 @@ template class xbt::Extendable; namespace s4u { +#ifndef DOXYGEN xbt::signal Host::on_creation; xbt::signal Host::on_destruction; xbt::signal Host::on_state_change; xbt::signal Host::on_speed_change; +#endif Host* Host::set_cpu(kernel::resource::CpuImpl* cpu) {