From f7005fe1bcd207eed0fb8eef4d2cc9a6457aa74b Mon Sep 17 00:00:00 2001
From: Martin Quinson <martin.quinson@loria.fr>
Date: Tue, 15 Dec 2015 23:03:18 +0100
Subject: [PATCH] rename Lib to Facetable

---
 include/simgrid/Host.hpp               |  4 ++--
 include/xbt/{Lib.hpp => Facetable.hpp} | 24 ++++++++++++++++++++----
 tools/cmake/DefinePackages.cmake       |  2 +-
 3 files changed, 23 insertions(+), 7 deletions(-)
 rename include/xbt/{Lib.hpp => Facetable.hpp} (57%)

diff --git a/include/simgrid/Host.hpp b/include/simgrid/Host.hpp
index e914303e8b..d61aefabfa 100644
--- a/include/simgrid/Host.hpp
+++ b/include/simgrid/Host.hpp
@@ -12,11 +12,11 @@
 #include <vector>
 
 #include <xbt/base.h>
-#include <xbt/Lib.hpp>
+#include <xbt/Facetable.hpp>
 
 namespace simgrid {
 
-XBT_PUBLIC_CLASS Host : public simgrid::xbt::Lib<Host> {
+XBT_PUBLIC_CLASS Host : public simgrid::xbt::Facetable<Host> {
 private:
   std::string id_;
 public:
diff --git a/include/xbt/Lib.hpp b/include/xbt/Facetable.hpp
similarity index 57%
rename from include/xbt/Lib.hpp
rename to include/xbt/Facetable.hpp
index 36c10b7ab0..08be86eb45 100644
--- a/include/xbt/Lib.hpp
+++ b/include/xbt/Facetable.hpp
@@ -14,8 +14,24 @@
 namespace simgrid {
 namespace xbt {
 
+/** A Facetable is an object that you can extend with external facets.
+ *
+ * Facets are similar to the concept of mixins, that is, a set of behavior that is injected into a class without derivation.
+ *
+ * Imagine that you want to write a plugin dealing with the energy in SimGrid.
+ * You will have to store some information about each and every host.
+ *
+ * You could modify the Host class directly (but your code will soon become messy).
+ * You could create a class EnergyHost deriving Host, but it is not easily combinable
+ *    with a notion of Host extended with another concept (such as mobility).
+ * You could completely externalize these data with an associative map Host->EnergyHost.
+ *    It would work, provided that you implement this classical feature correctly (and it would induce a little performance penalty).
+ * Instead, you should add a new facet to the Host class, that happens to be Facetable.
+ *
+ */
+
 template<class T>
-class Lib {
+class Facetable {
 private:
   static std::vector<void(*)(void*)> deleters_;
 protected:
@@ -32,8 +48,8 @@ public:
   {
     return add_level([](void* p){ delete (U*)p; });
   }
-  Lib() : facets_(deleters_.size(), nullptr) {}
-  ~Lib()
+  Facetable() : facets_(deleters_.size(), nullptr) {}
+  ~Facetable()
   {
     for (std::size_t i = 0; i < facets_.size(); ++i)
       if (facets_[i] != nullptr)
@@ -60,7 +76,7 @@ public:
 };
 
 template<class T>
-std::vector<void(*)(void*)> Lib<T>::deleters_ = {};
+std::vector<void(*)(void*)> Facetable<T>::deleters_ = {};
 
 }
 }
diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake
index cdb6b0ae4d..c5b99221f0 100644
--- a/tools/cmake/DefinePackages.cmake
+++ b/tools/cmake/DefinePackages.cmake
@@ -751,7 +751,7 @@ set(headers_to_install
   include/xbt/hash.h
   include/xbt/heap.h
   include/xbt/lib.h
-  include/xbt/Lib.hpp
+  include/xbt/Facetable.hpp
   include/xbt/log.h
   include/xbt/mallocator.h
   include/xbt/matrix.h
-- 
2.20.1