- 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.
intrusive_ptr_release
intrusive_ptr_add_ref
get_filtered_netzones_recursive
+simgrid::s4u::Storage
\ No newline at end of file
INPUT += ../../include/simgrid/s4u
INPUT += ../../include/simgrid/msg.h
INPUT += ../../src/msg/
+INPUT += ../../src/plugins/
RECURSIVE = YES
EXAMPLE_PATH = ../../examples
--- /dev/null
+.. _plugins:
+
+.. raw:: html
+
+ <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
+ <script>
+ window.onload=function() { // Wait for the SVG to be loaded before changing it
+ var elem=document.querySelector("#TOC").contentDocument.getElementById("PlatformBox")
+ elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
+ }
+ </script>
+ <br/>
+ <br/>
+
+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 <https://framagit.org/simgrid/simgrid/tree/master/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 <simgrid::s4u::Actor>`,
+:cpp:class:`Disks <simgrid::s4u::Disk>`,
+:cpp:class:`Hosts <simgrid::s4u::Host>` and
+:cpp:class:`Links <simgrid::s4u::Link>`. 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 <simgrid::s4u::Actor::on_creation>`
+ :cpp:member:`Actor::on_suspend <simgrid::s4u::Actor::on_suspend>`
+ :cpp:member:`Actor::on_resume <simgrid::s4u::Actor::on_resume>`
+ :cpp:member:`Actor::on_sleep <simgrid::s4u::Actor::on_sleep>`
+ :cpp:member:`Actor::on_wake_up <simgrid::s4u::Actor::on_wake_up>`
+ :cpp:member:`Actor::on_migration_start <simgrid::s4u::Actor::on_migration_start>`
+ :cpp:member:`Actor::on_migration_end <simgrid::s4u::Actor::on_migration_end>`
+ :cpp:member:`Actor::on_termination <simgrid::s4u::Actor::on_termination>`
+ :cpp:member:`Actor::on_destruction <simgrid::s4u::Actor::on_destruction>`
+- :cpp:member:`Comm::on_sender_start <simgrid::s4u::Comm::on_sender_start>`
+ :cpp:member:`Comm::on_receiver_start <simgrid::s4u::Comm::on_receiver_start>`
+ :cpp:member:`Comm::on_completion <simgrid::s4u::Comm::on_completion>`
+- :cpp:member:`Engine::on_platform_creation <simgrid::s4u::Engine::on_platform_creation>`
+ :cpp:member:`Engine::on_platform_created <simgrid::s4u::Engine::on_platform_created>`
+ :cpp:member:`Engine::on_time_advance <simgrid::s4u::Engine::on_time_advance>`
+ :cpp:member:`Engine::on_simulation_end <simgrid::s4u::Engine::on_simulation_end>`
+ :cpp:member:`Engine::on_deadlock <simgrid::s4u::Engine::on_deadlock>`
+- :cpp:member:`Exec::on_start <simgrid::s4u::Exec::on_start>`
+ :cpp:member:`Exec::on_completion <simgrid::s4u::Exec::on_completion>`
+- :cpp:member:`Host::on_creation <simgrid::s4u::Host::on_creation>`
+ :cpp:member:`Host::on_destruction <simgrid::s4u::Host::on_destruction>`
+ :cpp:member:`Host::on_state_change <simgrid::s4u::Host::on_state_change>`
+ :cpp:member:`Host::on_speed_change <simgrid::s4u::Host::on_speed_change>`
+- :cpp:member:`Link::on_creation <simgrid::s4u::Link::on_creation>`
+ :cpp:member:`Link::on_destruction <simgrid::s4u::Link::on_destruction>`
+ :cpp:member:`Link::on_state_change <simgrid::s4u::Link::on_state_change>`
+ :cpp:member:`Link::on_speed_change <simgrid::s4u::Link::on_bandwidth_change>`
+ :cpp:member:`Link::on_communicate <simgrid::s4u::Link::on_communicate>`
+ :cpp:member:`Link::on_communication_state_change <simgrid::s4u::Link::on_communication_state_change>`
+- :cpp:member:`Netzone::on_creation <simgrid::s4u::Netzone::on_creation>`
+ :cpp:member:`Netzone::on_seal <simgrid::s4u::Netzone::on_seal>`
+ :cpp:member:`Netzone::on_route_creation <simgrid::s4u::Netzone::on_route_creation>`
+- :cpp:member:`VirtualMachine::on_start <simgrid::s4u::VirtualMachine::on_start>`
+ :cpp:member:`VirtualMachine::on_started <simgrid::s4u::VirtualMachine::on_started>`
+ :cpp:member:`VirtualMachine::on_suspend <simgrid::s4u::VirtualMachine::on_suspend>`
+ :cpp:member:`VirtualMachine::on_resume <simgrid::s4u::VirtualMachine::on_resume>`
+ :cpp:member:`VirtualMachine::on_migration_start <simgrid::s4u::VirtualMachine::on_migration_start>`
+ :cpp:member:`VirtualMachine::on_migration_end <simgrid::s4u::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
Deploying your Application <Deploying_your_Application.rst>
The SimGrid Models <models.rst>
ns-3 as a SimGrid model <ns3.rst>
+ SimGrid Plugins <Plugins.rst>
Simulation Outcomes <outcomes.rst>
Use Cases and Howto <howto.rst>
The SimGrid Community <community.rst>
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:
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
/** @brief Simulation Agent */
class XBT_PUBLIC Actor : public xbt::Extendable<Actor> {
+#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) {}
/** 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<void(Actor&)> on_creation;
/** Signal to others that an actor has been suspended**/
static xbt::signal<void(Actor const&)> on_suspend;
bool currently_destroying_ = false;
public:
- /*** Called on each newly created host */
+ /** Called on each newly created host */
static xbt::signal<void(Host&)> on_creation;
- /*** Called just before destructing a host */
+ /** Called just before destructing a host */
static xbt::signal<void(Host const&)> 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<void(Host const&)> 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<void(Host const&)> on_speed_change;
/* **************************** 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.
*/
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.
/* **************************** 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().
*/
});
}
-/** @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
});
}
-/** @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.
return host->extension<HostEnergy>()->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)
return host->extension<HostEnergy>()->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)
"The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization.");
return host->extension<HostEnergy>()->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)
"The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization.");
return host->extension<HostEnergy>()->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)
"The Energy plugin is not active. Please call sg_host_energy_plugin_init() during initialization.");
return host->extension<HostEnergy>()->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)
*/
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<HostLoad>();
- 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<simgrid::s4u::VirtualMachine*>(&host)) // Ignore virtual machines
return;
// 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) {
host->extension<HostLoad>()->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);
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.
{
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().
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.
