From: Martin Quinson <martin.quinson@loria.fr>
Date: Thu, 11 Oct 2018 21:06:41 +0000 (+0200)
Subject: improve the doc of the host plugin API
X-Git-Tag: v3_22~907
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/0a0a04aa5d4d82074210bd07aca90661a1a62d76

improve the doc of the host plugin API
---

diff --git a/include/simgrid/plugins/load.h b/include/simgrid/plugins/load.h
index a9fa55af5b..a343091f6d 100644
--- a/include/simgrid/plugins/load.h
+++ b/include/simgrid/plugins/load.h
@@ -20,6 +20,10 @@ XBT_PUBLIC double sg_host_get_computed_flops(sg_host_t host);
 XBT_PUBLIC void sg_host_load_reset(sg_host_t host);
 
 #define MSG_host_load_plugin_init() sg_host_load_plugin_init()
+/** @brief Returns the current load of that host, as a ratio = achieved_flops / (core_current_speed * core_amount)
+ *
+ *  See simgrid::plugin::HostLoad::get_current_load() for the full documentation.
+ */
 #define MSG_host_get_current_load(host) sg_host_get_current_load(host)
 #define MSG_host_get_computed_flops(host) sg_host_get_computed_flops(host)
 #define MSG_host_get_avg_load(host) sg_host_get_avg_load(host)
diff --git a/src/bindings/java/org/simgrid/msg/Host.java b/src/bindings/java/org/simgrid/msg/Host.java
index b40704c5c6..53ccd9968f 100644
--- a/src/bindings/java/org/simgrid/msg/Host.java
+++ b/src/bindings/java/org/simgrid/msg/Host.java
@@ -144,12 +144,16 @@ public class Host {
 	 */
 	public native double getConsumedEnergy();
 
-	/** Returns the current load of the host */
+	/** Returns the current load of the host, as a ratio = achieved_flops / (core_current_speed * core_amount)
+	 *	
+	 * See simgrid::plugin::HostLoad::get_current_load() for the full documentation.
+	 */
 	public native double getCurrentLoad();
-	/** Returns the number of flops computed of the host */
+	/** Returns the number of flops computed of the host since the beginning of the simulation */
 	public native double getComputedFlops();
-	/** Returns the average load of the host */
+	/** Returns the average load of the host as a ratio since the beginning of the simulation*/
 	public native double getAvgLoad();
+   
 	/** Returns the current pstate */
 	public native int getPstate();
 	/** Changes the current pstate */
diff --git a/src/plugins/host_load.cpp b/src/plugins/host_load.cpp
index ad42f71b6f..f0605a8796 100644
--- a/src/plugins/host_load.cpp
+++ b/src/plugins/host_load.cpp
@@ -43,10 +43,17 @@ public:
   explicit HostLoad(simgrid::s4u::Host&& ptr) = delete;
 
   double get_current_load();
+  /** Get the the average load since last reset(), as a ratio
+   *
+   * That's the ratio (amount of flops that were actually computed) / (amount of flops that could have been computed at full speed)
+   */
   double get_average_load() { update(); return (theor_max_flops_ == 0) ? 0 : computed_flops_ / theor_max_flops_; };
+  /** Amount of flops computed since last reset() */
   double get_computed_flops() { update(); return computed_flops_; }
-  double get_idle_time() { update(); return idle_time_; } /** Return idle time since last reset */
-  double get_total_idle_time() { update(); return total_idle_time_; } /** Return idle time over the whole simulation */
+  /** Return idle time since last reset() */
+  double get_idle_time() { update(); return idle_time_; }
+  /** Return idle time over the whole simulation */
+  double get_total_idle_time() { update(); return total_idle_time_; }
   void update();
   void add_activity(simgrid::kernel::activity::ExecImplPtr activity);
   void reset();
@@ -121,18 +128,22 @@ void HostLoad::update()
   last_updated_  = now;
 }
 
-/**
- * WARNING: This function does not guarantee that you have the real load at any time imagine all actions on your CPU
- * terminate at time t. Your load is then 0. Then you query the load (still 0) and then another action starts (still at
- * time t!). This means that the load was never really 0 (because the time didn't advance) but it will still be reported
- * as 0.
+/** @brief Get the current load as a ratio = achieved_flops / (core_current_speed * core_amount)
+ *
+ * You may also want to check simgrid::s4u::Host::get_load() that simply returns
+ * the achieved flop rate (in flops per seconds), ie the load that a new action arriving on
+ * that host would suffer.
  *
- * So, use at your own risk.
+ * Please note that this function only returns an instantaneous load that may be deceiving
+ * in some scenarios. For example, imagine that an activity terminates at time t, and that
+ * another activity is created on the same host at the exact same timestamp. The load was
+ * never 0 on the simulated machine since the time did not advance between the two events.
+ * But still, if you call this function between the two events (in the simulator course), it
+ * returns 0 although there is no time (in the simulated time) where this value is valid.
  */
 double HostLoad::get_current_load()
 {
   // We don't need to call update() here because it is called every time an action terminates or starts
-  // FIXME: Can this happen at the same time? stop -> call to getCurrentLoad, load = 0 -> next action starts?
   return current_flops_ / static_cast<double>(host_->get_speed() * host_->get_core_count());
 }
 
@@ -182,8 +193,7 @@ static void on_action_state_change(simgrid::surf::CpuAction* action, simgrid::ke
 
 /* **************************** Public interface *************************** */
 
-/** @ingroup plugin_load
- * @brief Initializes the HostLoad plugin
+/** @brief Initializes the HostLoad plugin
  * @details The HostLoad plugin provides an API to get the current load of each host.
  */
 void sg_host_load_plugin_init()
@@ -240,9 +250,9 @@ void sg_host_load_plugin_init()
   simgrid::s4u::Host::on_speed_change.connect(&on_host_change);
 }
 
-/** @brief Returns the current load of the host passed as argument
+/** @brief Returns the current load of that host, as a ratio = achieved_flops / (core_current_speed * core_amount)
  *
- *  See also @ref plugin_load
+ *  See simgrid::plugin::HostLoad::get_current_load() for the full documentation.
  */
 double sg_host_get_current_load(sg_host_t host)
 {
diff --git a/src/s4u/s4u_Host.cpp b/src/s4u/s4u_Host.cpp
index adde454108..b44b000b23 100644
--- a/src/s4u/s4u_Host.cpp
+++ b/src/s4u/s4u_Host.cpp
@@ -223,7 +223,9 @@ double Host::get_speed() const
   return this->pimpl_cpu->get_speed(1.0);
 }
 /** @brief Returns the current computation load (in flops per second)
+ *
  * The external load (coming from an availability trace) is not taken in account.
+ * You may also be interested in the load plugin.
  */
 double Host::get_load() const
 {
@@ -630,4 +632,4 @@ sg_host_t sg_host_self()
 double sg_host_load(sg_host_t host)
 {
   return host->get_load();
-}
\ No newline at end of file
+}