From: Martin Quinson Date: Sat, 5 Oct 2019 23:49:42 +0000 (+0200) Subject: New doc section on plugins X-Git-Tag: v3.24~32 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/264c5991bbe2ec1c8f31a8ed68a83a8d1b656fa1 New doc section on plugins --- diff --git a/ChangeLog b/ChangeLog index 249843c987..0a926734df 100644 --- a/ChangeLog +++ b/ChangeLog @@ -58,6 +58,9 @@ Model-Checker: - MPI calls now MC_assert() that no MPI_ERR_* code is returned. This is useful to check for MPI compliance. +Documentation: + - New section on plugins: how to define a new one, and existing ones. + XBT: - xbt_mutex_t and xbt_cond_t are now marked as deprecated, a new C interface on S4U is already available to replace them by sg_mutex_t and sg_cond_t. diff --git a/docs/ignored_symbols b/docs/ignored_symbols index d72c68d560..f8f924418b 100644 --- a/docs/ignored_symbols +++ b/docs/ignored_symbols @@ -15,3 +15,4 @@ MSG_init_nocheck intrusive_ptr_release intrusive_ptr_add_ref get_filtered_netzones_recursive +simgrid::s4u::Storage \ No newline at end of file diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile index 509c698abe..22cefd9b82 100644 --- a/docs/source/Doxyfile +++ b/docs/source/Doxyfile @@ -3,6 +3,7 @@ INPUT = ../../include/simgrid/forward.h INPUT += ../../include/simgrid/s4u INPUT += ../../include/simgrid/msg.h INPUT += ../../src/msg/ +INPUT += ../../src/plugins/ RECURSIVE = YES EXAMPLE_PATH = ../../examples diff --git a/docs/source/Plugins.rst b/docs/source/Plugins.rst new file mode 100644 index 0000000000..efd66edac9 --- /dev/null +++ b/docs/source/Plugins.rst @@ -0,0 +1,111 @@ +.. _plugins: + +.. raw:: html + + + +
+
+ +SimGrid Plugins +############### + +You can extend SimGrid without modifying it, thanks to our plugin +mechanism. This page describes how to write your own plugin, and gives +the documentation of the ones distributed with SimGrid. + +- Host Energy: models the energy dissipation of the compute units. +- Link Energy: models the energy dissipation of the network. + +Defining a Plugin +***************** + +A plugin can get some additional code executed within the SimGrid +kernel, and attach the data needed by that code to the SimGrid +objects. + +The host load plugin in +`src/plugins/host_load.cpp `_ +constitutes a good introductory example. It defines a class +```HostLoad``` that is meant to be attached to each host. This class +contains a ```EXTENSION_ID``` field that is mandatory to our extension +mechanism. Then, the function ```sg_host_load_plugin_init``` +initializes the plugin. It first calls +:cpp:func:`simgrid::s4u::Host::extension_create()` to register its +extension to the ```s4u::Host``` objects, and then attaches some +callbacks to signals. + +You can attach your own extension to most kinds of s4u object: +:cpp:class:`Actors `, +:cpp:class:`Disks `, +:cpp:class:`Hosts ` and +:cpp:class:`Links `. If you need to extend another +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_migration_start ` + :cpp:member:`Actor::on_migration_end ` + :cpp:member:`Actor::on_termination ` + :cpp:member:`Actor::on_destruction ` +- :cpp:member:`Comm::on_sender_start ` + :cpp:member:`Comm::on_receiver_start ` + :cpp:member:`Comm::on_completion ` +- :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:`Link::on_creation ` + :cpp:member:`Link::on_destruction ` + :cpp:member:`Link::on_state_change ` + :cpp:member:`Link::on_speed_change ` + :cpp:member:`Link::on_communicate ` + :cpp:member:`Link::on_communication_state_change ` +- :cpp:member:`Netzone::on_creation ` + :cpp:member:`Netzone::on_seal ` + :cpp:member:`Netzone::on_route_creation ` +- :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 +**************** + +Only the major plugins are described here. Please check in src/plugins +to explore the other ones. + +.. _plugin_host_energy: + +Host Energy Plugin +================== + +.. doxygengroup:: Plugin_host_energy + +.. _plugin_link_energy: + +Link Energy Plugin +================== + +.. doxygengroup:: Plugin_link_energy + +.. LocalWords: SimGrid diff --git a/docs/source/index.rst b/docs/source/index.rst index dd414c6651..cc183c9303 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -78,6 +78,7 @@ of every page. Bugs in the code should be reported    Deploying your Application The SimGrid Models    ns-3 as a SimGrid model + SimGrid Plugins Simulation Outcomes Use Cases and Howto The SimGrid Community diff --git a/docs/source/platform_howtos.rst b/docs/source/platform_howtos.rst index cd61f105f8..b0826ed3d3 100644 --- a/docs/source/platform_howtos.rst +++ b/docs/source/platform_howtos.rst @@ -186,8 +186,9 @@ period and another one for the shutdown period. Of course, this is only one possible way to model these things. YMMV ;) .. _understanding_lv08 + Understanding the default TCP model -***************************** +*********************************** When simulating a data transfer between two hosts, you may be surprised by the obtained simulation time. Lets consider the following platform: @@ -208,6 +209,7 @@ simple latency-plus-size-divided-by-bandwidth model (0.01 + 8e5/1e6 = 0.81). However, the default TCP model of SimGrid is a bit more complex than that. It accounts for three phenomena that directly impact the simulation time even on such a simple example: + - The size of a message at the application level (i.e., 100kB in this example) is not the size that will actually be transferred over the network. To mimic the fact that TCP and IP headers are added to each packet of diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp index 0e336bad5e..d584d6dc11 100644 --- a/include/simgrid/s4u/Actor.hpp +++ b/include/simgrid/s4u/Actor.hpp @@ -124,12 +124,14 @@ namespace s4u { /** @brief Simulation Agent */ class XBT_PUBLIC Actor : public xbt::Extendable { +#ifndef DOXYGEN friend Exec; friend Mailbox; friend kernel::actor::ActorImpl; friend kernel::activity::MailboxImpl; kernel::actor::ActorImpl* const pimpl_; +#endif explicit Actor(smx_actor_t pimpl) : pimpl_(pimpl) {} @@ -148,7 +150,7 @@ public: /** Retrieve a reference to myself */ static Actor* self(); - /** Signal to others that a new actor has been created **/ + /** Fired when a new actor has been created **/ static xbt::signal on_creation; /** Signal to others that an actor has been suspended**/ static xbt::signal on_suspend; diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp index 7679ffa6fd..d06da0709f 100644 --- a/include/simgrid/s4u/Host.hpp +++ b/include/simgrid/s4u/Host.hpp @@ -50,13 +50,13 @@ private: bool currently_destroying_ = false; public: - /*** Called on each newly created host */ + /** Called on each newly created host */ static xbt::signal on_creation; - /*** Called just before destructing a host */ + /** Called just before destructing a host */ static xbt::signal on_destruction; - /*** Called when the machine is turned on or off (called AFTER the change) */ + /** Called when the machine is turned on or off (called AFTER the change) */ static xbt::signal on_state_change; - /*** Called when the speed of the machine is changed (called AFTER the change) + /** Called when the speed of the machine is changed (called AFTER the change) * (either because of a pstate switch or because of an external load event coming from the profile) */ static xbt::signal on_speed_change; diff --git a/src/plugins/host_dvfs.cpp b/src/plugins/host_dvfs.cpp index 02905091f7..0159926bda 100644 --- a/src/plugins/host_dvfs.cpp +++ b/src/plugins/host_dvfs.cpp @@ -439,7 +439,7 @@ static void on_host_added(simgrid::s4u::Host& host) /* **************************** Public interface *************************** */ -/** @ingroup SURF_plugin_load +/** * @brief Initializes the HostDvfs plugin * @details The HostDvfs plugin provides an API to get the current load of each host. */ diff --git a/src/plugins/host_energy.cpp b/src/plugins/host_energy.cpp index 419c1883df..b938f3fbcb 100644 --- a/src/plugins/host_energy.cpp +++ b/src/plugins/host_energy.cpp @@ -15,7 +15,7 @@ SIMGRID_REGISTER_PLUGIN(host_energy, "Cpu energy consumption.", &sg_host_energy_plugin_init) -/** @addtogroup plugin_energy +/** @defgroup plugin_host_energy This is the energy plugin, enabling to account not only for computation time, but also for the dissipated energy in the simulated platform. @@ -492,7 +492,7 @@ static void on_simulation_end() /* **************************** Public interface *************************** */ -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Enable host energy plugin * @details Enable energy plugin to get joules consumption of each cpu. Call this function before #MSG_init(). */ @@ -527,7 +527,7 @@ void sg_host_energy_plugin_init() }); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief updates the consumption of all hosts * * After this call, sg_host_get_consumed_energy() will not interrupt your process @@ -545,7 +545,7 @@ void sg_host_energy_update_all() }); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Returns the total energy consumed by the host so far (in Joules) * * Please note that since the consumption is lazily updated, it may require a simcall to update it. @@ -559,7 +559,7 @@ double sg_host_get_consumed_energy(sg_host_t host) return host->extension()->get_consumed_energy(); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Get the amount of watt dissipated when the host is idling */ double sg_host_get_idle_consumption(sg_host_t host) @@ -569,7 +569,7 @@ double sg_host_get_idle_consumption(sg_host_t host) return host->extension()->get_idle_consumption(); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Get the amount of watt dissipated at the given pstate when the host is idling */ double sg_host_get_wattmin_at(sg_host_t host, int pstate) @@ -578,7 +578,7 @@ double sg_host_get_wattmin_at(sg_host_t host, int pstate) "The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization."); return host->extension()->get_watt_min_at(pstate); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Returns the amount of watt dissipated at the given pstate when the host burns CPU at 100% */ double sg_host_get_wattmax_at(sg_host_t host, int pstate) @@ -587,7 +587,7 @@ double sg_host_get_wattmax_at(sg_host_t host, int pstate) "The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization."); return host->extension()->get_watt_max_at(pstate); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Returns the power slope at the given pstate */ double sg_host_get_power_range_slope_at(sg_host_t host, int pstate) @@ -596,7 +596,7 @@ double sg_host_get_power_range_slope_at(sg_host_t host, int pstate) "The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization."); return host->extension()->get_power_range_slope_at(pstate); } -/** @ingroup plugin_energy +/** @ingroup plugin_host_energy * @brief Returns the current consumption of the host */ double sg_host_get_current_consumption(sg_host_t host) diff --git a/src/plugins/host_load.cpp b/src/plugins/host_load.cpp index f3f7e3c3d8..85828913ba 100644 --- a/src/plugins/host_load.cpp +++ b/src/plugins/host_load.cpp @@ -184,21 +184,21 @@ static void on_host_change(simgrid::s4u::Host const& host) */ void sg_host_load_plugin_init() { - if (HostLoad::EXTENSION_ID.valid()) + if (HostLoad::EXTENSION_ID.valid()) // Don't do the job twice return; + // First register our extension of Hosts properly HostLoad::EXTENSION_ID = simgrid::s4u::Host::extension_create(); - if (simgrid::s4u::Engine::is_initialized()) { // If not yet initialized, this would create a new instance - // which would cause seg faults... + // If SimGrid is already initialized, we need to attach an extension to each existing host + if (simgrid::s4u::Engine::is_initialized()) { simgrid::s4u::Engine* e = simgrid::s4u::Engine::get_instance(); for (auto& host : e->get_all_hosts()) { host->extension_set(new HostLoad(host)); } } - /* When attaching a callback into a signal, you can use a lambda as follows, or a regular function as done below */ - + // Make sure that every future host also gets an extension (in case the platform is not loaded yet) simgrid::s4u::Host::on_creation.connect([](simgrid::s4u::Host& host) { if (dynamic_cast(&host)) // Ignore virtual machines return; @@ -218,7 +218,7 @@ void sg_host_load_plugin_init() // idle time. (Communication operations don't trigger this hook!) } else { // This runs on multiple hosts - XBT_DEBUG("HostLoad plugin currently does not support executions on several hosts"); + XBT_WARN("HostLoad plugin currently does not support executions on several hosts"); } }); simgrid::kernel::activity::ExecImpl::on_completion.connect([](simgrid::kernel::activity::ExecImpl const& activity) { @@ -231,7 +231,7 @@ void sg_host_load_plugin_init() host->extension()->update(); } else { // This runs on multiple hosts - XBT_DEBUG("HostLoad plugin currently does not support executions on several hosts"); + XBT_WARN("HostLoad plugin currently does not support executions on several hosts"); } }); simgrid::s4u::Host::on_state_change.connect(&on_host_change); diff --git a/src/plugins/link_energy.cpp b/src/plugins/link_energy.cpp index aff0b3130e..01b0babad2 100644 --- a/src/plugins/link_energy.cpp +++ b/src/plugins/link_energy.cpp @@ -14,8 +14,7 @@ SIMGRID_REGISTER_PLUGIN(link_energy, "Link energy consumption.", &sg_link_energy_plugin_init) -/** @addtogroup SURF_plugin_energy - +/** @defgroup plugin_link_energy This is the link energy plugin, accounting for the dissipated energy in the simulated platform. @@ -184,7 +183,7 @@ int sg_link_energy_is_inited() { return LinkEnergy::EXTENSION_ID.valid(); } -/** @ingroup SURF_plugin_energy +/** @ingroup plugin_link_energy * @brief Enable energy plugin * @details Enable energy plugin to get joules consumption of each cpu. You should call this function before * #MSG_init(). @@ -220,7 +219,7 @@ void sg_link_energy_plugin_init() simgrid::s4u::Engine::on_simulation_end.connect(&on_simulation_end); } -/** @ingroup plugin_energy +/** @ingroup plugin_link_energy * @brief Returns the total energy consumed by the link so far (in Joules) * * Please note that since the consumption is lazily updated, it may require a simcall to update it.