host-filtering example: improve doc, and add to documentation TOC

diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc
index 9350de1..f4f51c2 100644 (file)
--- a/examples/s4u/README.doc
+++ b/examples/s4u/README.doc
@@ -213,6 +213,10 @@ result in short reads and short write, as in reality.
 
 @section s4u_ex_platf Interacting with the platform
 
+ - <b>Retrieving the list of hosts matching a given criteria</b>.
+   @ref examples/s4u/engine-filtering/s4u-engine-filtering.cpp\n
+   Filtering the actors that match a given criteria is rather simple.
+
  - <b>User-defined properties</b>.
    @ref examples/s4u/platform-properties/s4u-platform-properties.cpp and 
    @ref examples/s4u/platform-properties/s4u-platform-properties_d.xml and
@@ -323,6 +327,7 @@ than the previous examples.
 @example examples/s4u/app-pingpong/s4u-app-pingpong.cpp
 @example examples/s4u/app-token-ring/s4u-app-token-ring.cpp
 @example examples/s4u/dht-chord/s4u-dht-chord.cpp
+@example examples/s4u/engine-filtering/s4u-engine-filtering.cpp
 @example examples/s4u/energy-boot/platform_boot.xml
 @example examples/s4u/energy-boot/s4u-energy-boot.cpp
 @example examples/s4u/energy-exec/s4u-energy-exec.cpp

diff --git a/examples/s4u/engine-filtering/s4u-engine-filtering.cpp b/examples/s4u/engine-filtering/s4u-engine-filtering.cpp
index d8e5866..c3e0e7e 100644 (file)
--- a/examples/s4u/engine-filtering/s4u-engine-filtering.cpp
+++ b/examples/s4u/engine-filtering/s4u-engine-filtering.cpp
@@ -3,12 +3,38 @@
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
 
-#include "xbt/log.h"
 #include <simgrid/s4u.hpp>
 
+/* This example shows how to use simgrid::s4u::Engine::get_filtered_hosts() to retrieve
+ * all hosts that match a given criteria. This criteria can be specified either with:
+ *   - an inlined callback
+ *   - a boolean function, such as filter_speed_more_than_50Mf() below
+ *   - a functor (= function object), that can either be stateless such as filter::SingleCore below, or that can save
+ *     state such as filter::FrequencyChanged below
+ *
+ * This file provides examples for each of these categories. You should implement your own filters in your code.
+ */
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(s4u_engine_filtering, "Messages specific for this s4u example");
 
 namespace filter {
+/* First example of thing that we can use as a filtering criteria: a simple boolean function */
+static bool filter_speed_more_than_50Mf(simgrid::s4u::Host* host)
+{
+  return host->getSpeed() > 50E6;
+}
+
+/* Second kind of thing that we can use as a filtering criteria: a functor (=function object).
+ * This one is a bit stupid: it's a lot of boilerplate over a dummy boolean function.
+ */
+class SingleCore {
+public:
+  bool operator()(simgrid::s4u::Host* host) { return host->get_core_count() == 1; }
+};
+
+/* This functor is a bit more complex, as it saves the current state when created.
+ * Then, it allows to easily retrieve the hosts which frequency changed since the functor creation.
+ */
 class FrequencyChanged {
   std::map<simgrid::s4u::Host*, int> host_list;
 
@@ -25,25 +51,13 @@ public:
 
   double get_old_speed(simgrid::s4u::Host* host) { return host_list.at(host); }
 };
-class SingleCore {
-public:
-  bool operator()(simgrid::s4u::Host* host) { return host->get_core_count() == 1; }
-};
-
-bool filter_speed_more_than_50Mf(simgrid::s4u::Host* host);
-bool filter_speed_more_than_50Mf(simgrid::s4u::Host* host)
-{
-  return host->getSpeed() > 50E6;
-}
 }
 int main(int argc, char* argv[])
 {
   simgrid::s4u::Engine e(&argc, argv);
   e.load_platform(argv[1]);
 
-  /**
-   * Use a lambda function to filter hosts: We only want multicore hosts
-   */
+  /* Use a lambda function to filter hosts: We only want multicore hosts */
   XBT_INFO("Hosts currently registered with this engine: %zu", e.get_host_count());
   std::vector<simgrid::s4u::Host*> list =
       e.get_filtered_hosts([](simgrid::s4u::Host* host) { return host->get_core_count() > 1; });
@@ -53,18 +67,13 @@ int main(int argc, char* argv[])
 
   xbt_assert(list.size() == 1);
 
-  /*
-   * Use a function object (functor) without memory
-   */
+  /* Use a function object (functor) without memory */
   list = e.get_filtered_hosts(filter::SingleCore());
 
   for (auto& host : list)
     XBT_INFO("The following hosts are SingleCore: %s", host->get_cname());
 
-  /**
-   * This just shows how to use a function object that uses
-   * memory to filter.
-   */
+  /* Use a function object that uses memory to filter */
   XBT_INFO("A simple example: Let's retrieve all hosts that changed their frequency");
   filter::FrequencyChanged filter(e);
   e.host_by_name("MyHost2")->set_pstate(2);
@@ -73,9 +82,7 @@ int main(int argc, char* argv[])
   for (auto& host : list)
     XBT_INFO("The following hosts changed their frequency: %s (from %.1ff to %.1ff)", host->get_cname(), host->getPstateSpeed(filter.get_old_speed(host)), host->getSpeed());
 
-  /*
-   * You can also just use any normal function (namespaced as well, if you want) to filter
-   */
+  /* You can also just use any regular function (namespaced on need) to filter  */
   list = e.get_filtered_hosts(filter::filter_speed_more_than_50Mf);
 
   for (auto& host : list)