SimGrid Plugins¶
You can extend SimGrid without modifying it, thanks to our plugin mechanism. This page describes how to write your own plugin, and documents some of the plugins distributed with SimGrid:
Host Load: monitors the load of the compute units.
Host Energy: models the energy dissipation of the compute units.
Link Energy: models the energy dissipation of the network.
WiFi Energy: models the energy dissipation of wifi links.
You can activate these plugins with the –cfg=plugin command
line option, for example with --cfg=plugin:host_energy
. You can get the full
list of existing plugins with --cfg=plugin:help
.
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
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:
Actors
,
Disks
,
Hosts
and
Links
. If you need to extend another
kind of objects, please let us now.
-
template<class
R
, class ...P
>
classsimgrid::xbt
::
signal
<R(P...)>¶ A signal/slot mechanism, where you can attach callbacks to a given signal, and then fire the signal.
The template parameter is the function signature of the signal (the return value currently ignored).
-
template<class
R
, class ...P
>simgrid::xbt::signal<R(P...)>
::
operator()
(P... args)¶ Fire that signal, invoking all callbacks.
Partial list of existing signals in s4u:
Actor::on_creation
Actor::on_suspend
Actor::on_resume
Actor::on_sleep
Actor::on_wake_up
Actor::on_host_change
Actor::on_termination
Actor::on_destruction
Disk::on_creation
Disk::on_destruction
Disk::on_state_change
Engine::on_platform_creation
Engine::on_platform_created
Engine::on_time_advance
Engine::on_simulation_end
Engine::on_deadlock
Host::on_creation
Host::on_destruction
Host::on_state_change
Host::on_speed_change
Link::on_creation
Link::on_destruction
Link::on_state_change
Link::on_speed_change
Link::on_communication_state_change
VirtualMachine::on_start
VirtualMachine::on_started
VirtualMachine::on_suspend
VirtualMachine::on_resume
VirtualMachine::on_migration_start
VirtualMachine::on_migration_end
Existing Plugins¶
Only the major plugins are described here. Please check in src/plugins to explore the other ones.
Host Energy¶
-
group
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. To activate this plugin, first call
sg_host_energy_plugin_init()
before your loading your platform, and then usesg_host_get_consumed_energy()
to retrieve the consumption of a given host.When the host is on, this energy consumption naturally depends on both the current CPU load and the host energy profile. According to our measurements, the consumption is somehow linear in the amount of cores at full speed, with an abnormality when all the cores are idle. The full details are in our scientific paper on that topic.
As a result, our energy model takes 4 parameters:
Idle
wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to do.Epsilon
wattage when all cores are at 0 or epsilon%, but not in Idle state.AllCores
wattage when all cores of the host are at 100%.Off
wattage when the host is turned off.
Here is an example of XML declaration:
<host id="HostA" speed="100.0Mf" core="4"> <prop id="wattage_per_state" value="100.0:120.0:200.0" /> <prop id="wattage_off" value="10" /> </host>
If only two values are given,
Idle
is used for the missingEpsilon
value.This example gives the following parameters:
Off
is 10 Watts;Idle
is 100 Watts;Epsilon
is 120 Watts andAllCores
is 200 Watts. This is enough to compute the wattage as a function of the amount of loaded cores:#Cores loaded Wattage Explanation 0 (idle) 100 Watts Idle value 0 (not idle) 120 Watts Epsilon value 1 140 Watts Linear extrapolation between Epsilon and AllCores 2 160 Watts Linear extrapolation between Epsilon and AllCores 3 180 Watts Linear extrapolation between Epsilon and AllCores 4 200 Watts AllCores value How does DVFS interact with the host energy model?
If your host has several DVFS levels (several pstates), then you should give the energetic profile of each pstate level:
<host id="HostC" speed="100.0Mf,50.0Mf,20.0Mf" core="4"> <prop id="wattage_per_state" value="95.0:120.0:200.0, 93.0:115.0:170.0, 90.0:110.0:150.0" /> <prop id="wattage_off" value="10" /> </host>
This encodes the following values:
pstate Performance Idle Epsilon AllCores 0 100 Mflop/s 95 Watts 120 Watts 200 Watts 1 50 Mflop/s 93 Watts 115 Watts 170 Watts 2 20 Mflop/s 90 Watts 110 Watts 150 Watts To change the pstate of a given CPU, use the following functions:
MSG_host_get_nb_pstates()
,simgrid::s4u::Host::set_pstate()
,MSG_host_get_power_peak_at()
.How accurate are these models?
This model cannot be more accurate than your instantiation: with the default values, your result will not be accurate at all. You can still get accurate energy prediction, provided that you carefully instantiate the model. The first step is to ensure that your timing prediction match perfectly. But this is only the first step of the path, and you really want to read this paper to see all what you need to do before you can get accurate energy predictions.
Functions
-
void
sg_host_energy_plugin_init
()¶ Enable host energy plugin.
Enable energy plugin to get joules consumption of each cpu. Call this function before loading your platform.
-
void
sg_host_energy_update_all
()¶ updates the consumption of all hosts
After this call, sg_host_get_consumed_energy() will not interrupt your process (until after the next clock update).
-
double
sg_host_get_consumed_energy
(const_sg_host_t host)¶ 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. The result is that the actor requesting this value will be interrupted, the value will be updated in kernel mode before returning the control to the requesting actor.
-
double
sg_host_get_idle_consumption
(const_sg_host_t host)¶ Get the amount of watt dissipated when the host is idling.
-
double
sg_host_get_idle_consumption_at
(const_sg_host_t host, int pstate)¶ Get the amount of watt dissipated at the given pstate when the host is idling.
-
double
sg_host_get_wattmin_at
(const_sg_host_t host, int pstate)¶ Get the amount of watt dissipated at the given pstate when the host is at 0 or epsilon% CPU usage.
-
double
sg_host_get_wattmax_at
(const_sg_host_t host, int pstate)¶ Returns the amount of watt dissipated at the given pstate when the host burns CPU at 100%.
-
double
sg_host_get_power_range_slope_at
(const_sg_host_t host, int pstate)¶ Returns the power slope at the given pstate.
-
double
sg_host_get_current_consumption
(const_sg_host_t host)¶ Returns the current consumption of the host.
Link Energy¶
-
group
plugin_link_energy
This is the link energy plugin, accounting for the dissipated energy in the simulated platform.
The energy consumption of a link depends directly on its current traffic load. Specify that consumption in your platform file as follows:
<link id="SWITCH1" bandwidth="125Mbps" latency="5us" sharing_policy="SHARED" > <prop id="wattage_range" value="100.0:200.0" /> <prop id="wattage_off" value="10" /> </link>
The first property means that when your link is switched on, but without anything to do, it will dissipate 100 Watts. If it’s fully loaded, it will dissipate 200 Watts. If its load is at 50%, then it will dissipate 150 Watts. The second property means that when your host is turned off, it will dissipate only 10 Watts (please note that these values are arbitrary).
To simulate the energy-related elements, first call the sg_link_energy_plugin_init() before loading the platform and then use the following function to retrieve the consumption of a given link: sg_link_get_consumed_energy().
Functions
-
void
sg_link_energy_plugin_init
()¶ Enable energy plugin.
Enable energy plugin to get joules consumption of each cpu. You should call this function before loading your platform.
-
double
sg_link_get_consumed_energy
(const_sg_link_t link)¶ 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. The result is that the actor requesting this value will be interrupted, the value will be updated in kernel mode before returning the control to the requesting actor.
-
void
WiFi Energy¶
-
group
plugin_link_energy_wifi
This is the WiFi energy plugin, accounting for the dissipated energy of WiFi links.
Functions
-
void
sg_wifi_energy_plugin_init
()¶ Initialize the wifi energy plugin.
-
void
Host Load¶
-
group
plugin_host_load
In addition, this constitutes a good introductory example on how to write a plugin. It attaches an extension to each host to store some data, and places callbacks in the following signals:
simgrid::s4u::Host::on_creation_cb()
: Attach a new extension to the newly created host.simgrid::s4u::Exec::on_start_cb()
: Make note that a new execution started, increasing the load.simgrid::s4u::Exec::on_completion_cb()
: Make note that an execution completed, decreasing the load.simgrid::s4u::Host::on_state_change_cb()
: Do what is appropriate when the host gets suspended, turned off or similar.simgrid::s4u::Host::on_speed_change_cb()
: Do what is appropriate when the DVFS is modified.
Note that extensions are automatically destroyed when the host gets destroyed.
Functions
-
void
sg_host_load_plugin_init
()¶ Initializes the HostLoad plugin.
-
double
sg_host_get_current_load
(const_sg_host_t host)¶ Returns the current load of that host, as a ratio = achieved_flops / (core_current_speed * core_amount)
-
double
sg_host_get_avg_load
(const_sg_host_t host)¶ Returns the current load of that host.
-
double
sg_host_get_idle_time
(const_sg_host_t host)¶ Returns the time this host was idle since the last reset.
-
double
sg_host_get_total_idle_time
(const_sg_host_t host)¶ Returns the time this host was idle since the beginning of the simulation.
-
double
sg_host_get_computed_flops
(const_sg_host_t host)¶ Returns the amount of flops computed by that host since the last reset.
-
void
sg_host_load_reset
(const_sg_host_t host)¶ Resets the idle time and flops amount of that host.
File System¶
-
group
plugin_filesystem
This adds the notion of Files on top of the storage notion that provided by the core of SimGrid. Activate this plugin at will.
Typedefs
-
typedef s4u_File *
sg_file_t
¶ Pointer to a SimGrid file object
-
typedef const s4u_File *
const_sg_file_t
¶ Constant pointer to a SimGrid file object
Functions
-
void
sg_storage_file_system_init
()¶ Initialize the file system plugin.
See the examples in I/O on Disks and Files.
-
const char *
sg_file_get_name
(const_sg_file_t fd)¶ Retrieves the path to the file
-
sg_size_t
sg_file_get_size
(const_sg_file_t fd)¶ Retrieves the size of the file
-
void *
sg_file_get_data
(const_sg_file_t fd)¶ Retrieves the user data associated with the file
-
void
sg_file_seek
(sg_file_t fd, sg_offset_t offset, int origin)¶ Set the file position indicator in the sg_file_t by adding offset bytes to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).
- Parameters
fd
: : file object that identifies the streamoffset
: : number of bytes to offset from originorigin
: : Position used as reference for the offset. It is specified by one of the following constants defined in <stdio.h> exclusively to be used as arguments for this function (SEEK_SET = beginning of file, SEEK_CUR = current position of the file pointer, SEEK_END = end of file)
-
int
sg_file_rcopy
(sg_file_t file, sg_host_t host, const char *fullpath)¶ Copy a file to another location on a remote host.
- Return
If successful, the function returns 0. Otherwise, it returns -1.
- Parameters
file
: : the file to movehost
: : the remote host where the file has to be copiedfullpath
: : the complete path destination on the remote host
-
int
sg_file_rmove
(sg_file_t file, sg_host_t host, const char *fullpath)¶ Move a file to another location on a remote host.
- Return
If successful, the function returns 0. Otherwise, it returns -1.
- Parameters
file
: : the file to movehost
: : the remote host where the file has to be movedfullpath
: : the complete path destination on the remote host
-
sg_size_t
write
(sg_size_t size, bool write_inside = false)¶ Write into a file (local or remote)
Simulates a write action. Returns the size of data actually written.
- Return
the number of bytes successfully write or -1 if an error occurred
- Parameters
size
: of the file to writewrite_inside
:
-
class
File
: public xbt::Extendable<File>¶ - #include <file_system.h>
A simulated file.
Used to simulate the time it takes to access to a file, but does not really store any information.
They are located on simgrid::s4u::Disk that are accessed from a given simgrid::s4u::Host
-
typedef s4u_File *