From 083d77ba08970f47b704a3481eb0179259351ccb Mon Sep 17 00:00:00 2001
From: quemy <alexandre.quemy@gmail.com>
Date: Tue, 20 Nov 2012 22:08:30 +0100
Subject: [PATCH] Islands send pop to IslandModel. Add and clean documentation.

---
 smp/src/MWModel.cpp                  | 10 ++--
 smp/src/PPExpander.h                 |  6 ++-
 smp/src/abstractIsland.h             |  6 +++
 smp/src/algoDispatching.h            |  4 +-
 smp/src/bimap.h                      | 13 ++++-
 smp/src/contDispatching.h            | 20 +++++---
 smp/src/contWrapper.h                |  2 +
 smp/src/island.cpp                   | 12 +++++
 smp/src/island.h                     | 17 ++++--
 smp/src/islandModel.cpp              | 77 ++++++++++++++++++++++++++++
 smp/src/islandModel.h                | 60 ++++++++--------------
 smp/src/islandNotifier.h             |  4 +-
 smp/src/migPolicy.h                  |  4 +-
 smp/src/policiesDispatching.h        |  4 +-
 smp/src/policyElement.cpp            | 10 ++--
 smp/src/policyElement.h              | 19 ++++---
 smp/src/scheduler.h                  |  7 ++-
 smp/src/topology/booleanTopology.cpp |  1 +
 smp/test/CMakeLists.txt              |  3 +-
 smp/test/t-smpIsland.cpp             |  4 +-
 20 files changed, 205 insertions(+), 78 deletions(-)
 create mode 100644 smp/src/islandModel.cpp

diff --git a/smp/src/MWModel.cpp b/smp/src/MWModel.cpp
index 6ec45d89c..cde545c77 100644
--- a/smp/src/MWModel.cpp
+++ b/smp/src/MWModel.cpp
@@ -29,19 +29,21 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 
 template<template <class> class EOAlgo, class EOT, class Policy>
 template<class... Args>
-paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::MWModel (unsigned workersNb, Args&... args) :
+paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::MWModel(unsigned workersNb, Args&... args) :
     EOAlgo<EOT>(args...),
     scheduler(workersNb)
-{ assert(workersNb > 0); }
+{ 
+    assert(workersNb > 0); 
+}
 
 template<template <class> class EOAlgo, class EOT, class Policy>
 template<class... Args>
-paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::MWModel (Args&... args) :
+paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::MWModel(Args&... args) :
     MWModel(Thread::hardware_concurrency(), args...)
 {}
 
 template<template <class> class EOAlgo, class EOT, class Policy>
-paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::~MWModel () 
+paradiseo::smp::MWModel<EOAlgo,EOT,Policy>::~MWModel() 
 {}
 
 template<template <class> class EOAlgo, class EOT, class Policy>
diff --git a/smp/src/PPExpander.h b/smp/src/PPExpander.h
index b22984fda..f4c740684 100644
--- a/smp/src/PPExpander.h
+++ b/smp/src/PPExpander.h
@@ -1,5 +1,5 @@
 /*
-<PPE.h>
+<PPExpander.h>
 Copyright (C) DOLPHIN Project-Team, INRIA Lille - Nord Europe, 2006-2012
 
 Alexandre Quemy, Thibault Lasnier - INSA Rouen
@@ -31,7 +31,9 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 #define PPE_H_
 
 /** Parameter Pack Expansion: Utility file to expand parameter pack
-/* Utility file to expand parameter pack with the recursive method
+
+Utility file to expand parameter pack with the recursive method
+
 **/
 
 template<class... Arg> class Loop;
diff --git a/smp/src/abstractIsland.h b/smp/src/abstractIsland.h
index 4fa2178f0..cab0c85c7 100644
--- a/smp/src/abstractIsland.h
+++ b/smp/src/abstractIsland.h
@@ -46,6 +46,8 @@ class IslandModel;
 
 /** AbstractIsland: An abstract island.
 
+The abstract island is used to manipulate island pointers wihout the knowledge of the algorithm.
+
 @see smp::Island
 */
 
@@ -77,6 +79,10 @@ public:
      */
     virtual void check(void) = 0;
     
+    /**
+     * Check if the algorithm is stopped.
+     * @return true if stopped
+     */
     virtual bool isStopped(void) = 0;
     
 };
diff --git a/smp/src/algoDispatching.h b/smp/src/algoDispatching.h
index abbc604f6..286a877cf 100644
--- a/smp/src/algoDispatching.h
+++ b/smp/src/algoDispatching.h
@@ -37,7 +37,9 @@ namespace paradiseo
 namespace smp
 {
 /** Algo Dispatching
-* The Algo Dispatching enable to choose the algorithm to call at compile time by tag-dispatching method
+
+The Algo Dispatching enable to choose the algorithm to call at compile time by tag-dispatching method
+
 **/
 
 // Main algorithms tags
diff --git a/smp/src/bimap.h b/smp/src/bimap.h
index 2c8e42f82..3ab21ec37 100644
--- a/smp/src/bimap.h
+++ b/smp/src/bimap.h
@@ -37,12 +37,22 @@ namespace paradiseo
 {
 namespace smp
 {
+/** Bimap
 
+Bidirectional map in order to create a bijection between islands and vertices.
+A and B objects are stocked in two std::set, then if you would avoid instances duplications,
+template A and B with pointers.
+
+**/
 template<class A, class B>
 class Bimap
 {
 public:
-    
+    /**
+     * Add a relation 
+     * @param workersNb the number of workers
+     * @param args... list of parameters according to the constructor of your algorithm
+     */
     void add(A a, B b)
     {
         ASet.insert(a);
@@ -51,6 +61,7 @@ public:
         leftAssociation[&b] = &a;
     }
     
+    
     B& getRight(A const a)
     {
         return *rightAssociation[&a];
diff --git a/smp/src/contDispatching.h b/smp/src/contDispatching.h
index 377226312..63d9c11bb 100644
--- a/smp/src/contDispatching.h
+++ b/smp/src/contDispatching.h
@@ -31,27 +31,33 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 #define CONT_D_H_
 
 /** Continuator Dispatching
-* The Continuator Dispatching enable to wrap continuator in Island constructor for a better user interface
+
+The Continuator Dispatching enable to wrap continuators in Island constructor for a better user interface
+
 **/
 
 template<class T, class U>
 U& wrap_pp_impl(T&, U& u, std::false_type)
-{ return u; }
+{ 
+    return u; 
+}
 
 template<class T, class U>
 T& wrap_pp_impl(T& t, U&, std::true_type)
-{ return t; }
+{ 
+    return t; 
+}
 
 template<class T, class U>
-struct result_of_wrap_pp :
-  std::conditional<std::is_base_of<T,U>::value,T&,U&>
+struct result_of_wrap_pp : 
+    std::conditional<std::is_base_of<T,U>::value,T&,U&>
 {};
 
 template<class T, class U>
 typename result_of_wrap_pp<T,U>::type wrap_pp(T& t, U& u)
 { 
-  typedef typename std::is_base_of<T,U>::type tag;
-  return wrap_pp_impl(t,u,tag());
+    typedef typename std::is_base_of<T,U>::type tag;
+    return wrap_pp_impl(t,u,tag());
 }
 
 #endif
diff --git a/smp/src/contWrapper.h b/smp/src/contWrapper.h
index 75cadbce6..68511ce4a 100644
--- a/smp/src/contWrapper.h
+++ b/smp/src/contWrapper.h
@@ -46,6 +46,8 @@ namespace smp
 /** ContWrapper: Utility class to wrap the algorithm continuators with island notifier.
 
 Utility class to wrap the algorithm continuators with island notifier during the island construction.
+By using the wrapper, we do not have to modify original continuators inside the IslandModel and then,
+it avoids some side effects.
 
 */
 template<class EOT>
diff --git a/smp/src/island.cpp b/smp/src/island.cpp
index 51b399d5c..56e7bf7e4 100644
--- a/smp/src/island.cpp
+++ b/smp/src/island.cpp
@@ -29,6 +29,7 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 
 #include <type_traits>
 
+
 template<template <class> class EOAlgo, class EOT>
 template<class... Args>
 paradiseo::smp::Island<EOAlgo,EOT>::Island(unsigned _popSize, eoInit<EOT>& _chromInit, IntPolicy<EOT>& _intPolicy, MigPolicy<EOT>& _migPolicy, Args&... args) :
@@ -51,6 +52,9 @@ void paradiseo::smp::Island<EOAlgo,EOT>::operator()()
 {
     stopped = false;
     algo(pop);
+    // Let's wait the end of communications with the island model
+    for(auto& message : sentMessages)
+        message.join();
     stopped = true;
 }
 
@@ -100,6 +104,14 @@ void paradiseo::smp::Island<EOAlgo,EOT>::send(eoSelect<EOT>& _select)
     eoPop<EOT> migPop;
     _select(pop, migPop);
     //std::cout << "   La population migrante est :" << std::endl << migPop << std::endl;
+    
+    // Delete delivered messages
+    for(auto it = sentMessages.begin(); it != sentMessages.end(); it++)
+        if(!it->joinable())
+            sentMessages.erase(it);
+  
+    sentMessages.push_back(std::thread(&IslandModel<EOT>::update, model, migPop, this));
+
 }
 
 template<template <class> class EOAlgo, class EOT>
diff --git a/smp/src/island.h b/smp/src/island.h
index ec3f31769..55ec1bde2 100644
--- a/smp/src/island.h
+++ b/smp/src/island.h
@@ -48,6 +48,12 @@ namespace paradiseo
 {
 namespace smp
 {
+/** Island: Concrete island that wraps an algorithm
+
+The island wraps an algorithm and provide mecanism for emigration and integration of populations.
+
+@see smp::AbstractIsland, smp::MigPolicy
+*/
 
 template<template <class> class EOAlgo, class EOT>
 class Island : private ContWrapper<EOT>, public AIsland<EOT>
@@ -59,7 +65,7 @@ public:
      * @param _chromInit Population initializer.
      * @param _intPolicy Integration policy
      * @param _migPolicy Migration policy
-     * @param args Parameters to construct the algorithm of the island.
+     * @param args Parameters to construct the algorithm.
      */
     template<class... Args>
     Island(unsigned _popSize, eoInit<EOT>& _chromInit, IntPolicy<EOT>& _intPolicy, MigPolicy<EOT>& _migPolicy, Args&... args);
@@ -92,7 +98,11 @@ public:
      */
     virtual void check(void);
     
-    virtual bool isStopped(void);
+    /**
+     * Check if the algorithm is stopped.
+     * @return true if stopped
+     */
+    virtual bool isStopped(void); 
     
 protected:
 
@@ -107,13 +117,14 @@ protected:
      */
     virtual void receive(void);
     
-    IslandModel<EOT>* model;
+    IslandModel<EOT>* model;                
     eoPop<EOT> pop;
     EOAlgo<EOT> algo;
     std::queue<eoPop<EOT>*> listImigrants;
     IntPolicy<EOT>& intPolicy;
     MigPolicy<EOT>& migPolicy;
     std::atomic<bool> stopped;
+    std::vector<std::thread> sentMessages;
 };
 
 #include <island.cpp>
diff --git a/smp/src/islandModel.cpp b/smp/src/islandModel.cpp
new file mode 100644
index 000000000..b478c7d48
--- /dev/null
+++ b/smp/src/islandModel.cpp
@@ -0,0 +1,77 @@
+/*
+<islandModel.cpp>
+Copyright (C) DOLPHIN Project-Team, INRIA Lille - Nord Europe, 2006-2012
+
+Alexandre Quemy, Thibault Lasnier - INSA Rouen
+
+This software is governed by the CeCILL license under French law and
+abiding by the rules of distribution of free software.  You can  ue,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+ParadisEO WebSite : http://paradiseo.gforge.inria.fr
+Contact: paradiseo-help@lists.gforge.inria.fr
+*/
+
+template<class EOT>
+void paradiseo::smp::IslandModel<EOT>::add(AIsland<EOT>& _island)
+{
+    static unsigned i = 0;
+    islands[i] = &_island;
+    islands[i]->setModel(this);
+    i++;
+}
+
+template<class EOT>
+void paradiseo::smp::IslandModel<EOT>::operator()()
+{
+    std::vector<Thread> threads(islands.size());
+
+    unsigned i = 0;
+    for(auto it : islands)
+    {
+        threads[i].start(&AIsland<EOT>::operator(), it.second);
+        i++;
+    }
+
+    unsigned workingThread = islands.size();
+    while(workingThread > 0)
+    {
+        workingThread = islands.size();
+        for(auto& it : islands)
+            if(it.second->isStopped())
+                workingThread--;
+        std::this_thread::sleep_for(std::chrono::nanoseconds(10));
+    }
+        
+    for(auto& thread : threads)
+        thread.join();
+        
+}
+
+template<class EOT>  
+void paradiseo::smp::IslandModel<EOT>::update(eoPop<EOT> _data, AIsland<EOT>* _island)
+{
+    std::cout << "Pop reçue par le médiateur" << std::endl;
+    std::lock_guard<std::mutex> lock(this->m);
+
+    std::cout << _data << std::endl;
+    listEmigrants.push(std::pair<eoPop<EOT>,AIsland<EOT>*>(_data, _island));
+}
+    
+
+
diff --git a/smp/src/islandModel.h b/smp/src/islandModel.h
index 405d27876..5ba24f9bf 100644
--- a/smp/src/islandModel.h
+++ b/smp/src/islandModel.h
@@ -1,5 +1,5 @@
 /*
-<IslandModel.h>
+<islandModel.h>
 Copyright (C) DOLPHIN Project-Team, INRIA Lille - Nord Europe, 2006-2012
 
 Alexandre Quemy, Thibault Lasnier - INSA Rouen
@@ -45,57 +45,41 @@ namespace smp
 
 /** IslandModel
 
+The IslandModel object is an island container that provides mecanism in order to perform a
+island model pattern according to a topology.
+
+@see smp::Island, smp::MigPolicy
 */
 
 template<class EOT>
 class IslandModel
 {
 public:
-    void add(AIsland<EOT>& _island)
-    {
-        static unsigned i = 0;
-        islands[i] = &_island;
-        islands[i]->setModel(this);
-        i++;
-    }
+    /**
+     * Add an island to the model.
+     * @param _island Island to add.
+     */
+    void add(AIsland<EOT>& _island);
 
-    void operator()()
-    {
-        std::vector<Thread> threads(islands.size());
-
-        unsigned i = 0;
-        for(auto it : islands)
-        {
-            threads[i].start(&AIsland<EOT>::operator(), it.second);
-            i++;
-        }
-
-        unsigned workingThread = islands.size();
-        while(workingThread > 0)
-        {
-            workingThread = islands.size();
-            for(auto& it : islands)
-                if(it.second->isStopped())
-                    workingThread--;
-            std::this_thread::sleep_for(std::chrono::nanoseconds(10));
-        }
-        
-        for(auto& thread : threads)
-            thread.join();
-        
-    }
+    /**
+     * Launch the island model by starting islands on their population.
+     */
+    void operator()();
     
-    void update(eoPop<EOT>* _data, AIsland<EOT>* _island)
-    {
-        listEmigrants.insert(std::pair<eoPop<EOT>*,AIsland<EOT>*>(_data, _island));
-    }
+    /**
+     * Update the island model by adding population to send in the emigrants list.
+     */
+    void update(eoPop<EOT> _data, AIsland<EOT>* _island);
     
 protected:
-    std::queue<std::pair<eoPop<EOT>*,AIsland<EOT>*>> listEmigrants;
+    std::queue<std::pair<eoPop<EOT>,AIsland<EOT>*>> listEmigrants;
     Bimap<unsigned, unsigned> table;
     std::map<unsigned, AIsland<EOT>*> islands;
+    std::mutex m;
 };
 
+#include <islandModel.cpp>
+
 }
 
 }
diff --git a/smp/src/islandNotifier.h b/smp/src/islandNotifier.h
index 267f2897e..09c837cb7 100644
--- a/smp/src/islandNotifier.h
+++ b/smp/src/islandNotifier.h
@@ -36,8 +36,8 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 /** IslandNotifier: The notifier will perform the binded task each generation.
 
 The island notifier makes the binded task executed by the island which observes.
-We can imagine that a continuator check is we have to execute the binded task.
-At the moment the task is perfermed each generation.
+We can imagine that a continuator checks if we have to execute the binded task.
+At the moment, the task is performed each generation.
 
 */
 
diff --git a/smp/src/migPolicy.h b/smp/src/migPolicy.h
index 29ea6cc22..d93a1c3a9 100644
--- a/smp/src/migPolicy.h
+++ b/smp/src/migPolicy.h
@@ -1,5 +1,5 @@
 /*
-<policy.h>
+<migPolicy.h>
 Copyright (C) DOLPHIN Project-Team, INRIA Lille - Nord Europe, 2006-2012
 
 Alexandre Quemy, Thibault Lasnier - INSA Rouen
@@ -37,7 +37,7 @@ namespace paradiseo
 {
 namespace smp
 {
-/** MigPolicy: Migration policy
+/** MigPolicy: Migration policy is a vector of PolicyElement.
 */
 
 template <class EOT> 
diff --git a/smp/src/policiesDispatching.h b/smp/src/policiesDispatching.h
index 0d5aba860..13b143688 100644
--- a/smp/src/policiesDispatching.h
+++ b/smp/src/policiesDispatching.h
@@ -37,7 +37,9 @@ namespace paradiseo
 namespace smp
 {
 /** Policies Dispatching
-* The Policies Dispatching enable to choose the policy to call at compile time by tag-dispatching method
+
+The Policies Dispatching enable to choose the policy to call at compile time by tag-dispatching method
+
 **/
 
 struct LinearPolicy {};
diff --git a/smp/src/policyElement.cpp b/smp/src/policyElement.cpp
index b49fe388e..ac5d7df9a 100644
--- a/smp/src/policyElement.cpp
+++ b/smp/src/policyElement.cpp
@@ -31,9 +31,9 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 #include <eo>
 
 template <class EOT>
-paradiseo::smp::PolicyElement<EOT>::PolicyElement(eoSelect<EOT>& _selection, eoContinue<EOT>& _criteria) :
+paradiseo::smp::PolicyElement<EOT>::PolicyElement(eoSelect<EOT>& _selection, eoContinue<EOT>& _criterion) :
     selection(_selection),
-    criteria(_criteria)
+    criterion(_criterion)
 { }
     
 template <class EOT>
@@ -45,13 +45,13 @@ bool paradiseo::smp::PolicyElement<EOT>::operator()(const eoPop<EOT>& _pop)
     //i++;
     // END DEBUG
         
-    return criteria(_pop);
+    return criterion(_pop);
 }
     
 template <class EOT>
-void paradiseo::smp::PolicyElement<EOT>::addCriteria(eoContinue<EOT>& _criteria)
+void paradiseo::smp::PolicyElement<EOT>::addCriterion(eoContinue<EOT>& _criterion)
 {
-    criteria.add(_criteria);
+    criterion.add(_criterion);
 }
     
 template <class EOT>
diff --git a/smp/src/policyElement.h b/smp/src/policyElement.h
index 9d1545bcb..af67fd2e1 100644
--- a/smp/src/policyElement.h
+++ b/smp/src/policyElement.h
@@ -36,6 +36,11 @@ namespace paradiseo
 {
 namespace smp
 {
+/** PolicyElement: PolicyElement is an element of a migration policy.
+
+The policy element is a pair of a selection method and a criterion to apply the selection.
+
+*/
 
 template <class EOT>
 class PolicyElement : public eoContinue<EOT>
@@ -44,22 +49,22 @@ public :
     /**
      * Constructor
      * @param _selection How to select elements for migration
-     * @param _criteria When notifying the island
+     * @param _criterion When notifying the island
      */
-    PolicyElement(eoSelect<EOT>& _selection, eoContinue<EOT>& _criteria);
+    PolicyElement(eoSelect<EOT>& _selection, eoContinue<EOT>& _criterion);
     
     /**
-     * Check is the criteria is reach
+     * Check is the criterion is reach
      * @param _pop Population which is checked by the criteria.
-     * @return false if the criteria is reached.
+     * @return false if the criterion is reached.
      */
     bool operator()(const eoPop<EOT>& _pop);
     
     /**
      * Add criteria for the same selection method.
-     * @param _criteria New criteria.
+     * @param _criterion New criterion.
      */
-    void addCriteria(eoContinue<EOT>& _criteria);
+    void addCriterion(eoContinue<EOT>& _criterion);
     
      /**
      * Access to the selection method.
@@ -69,7 +74,7 @@ public :
     
 protected :
     eoSelect<EOT>& selection;
-    eoContinue<EOT>& criteria;
+    eoContinue<EOT>& criterion;
 };
 
 #include <policyElement.cpp>
diff --git a/smp/src/scheduler.h b/smp/src/scheduler.h
index cb09a368b..11ef5c374 100644
--- a/smp/src/scheduler.h
+++ b/smp/src/scheduler.h
@@ -46,9 +46,12 @@ namespace paradiseo
 {
 namespace smp
 {
-/** 
-A scheduler class
+/** Scheduler : Dispatch load between workers according to a policy.
+
+Dispatch load between the specified number of workers according to a policy.
+
 */
+
 template<class EOT, class Policy = LinearPolicy>
 class Scheduler
 {
diff --git a/smp/src/topology/booleanTopology.cpp b/smp/src/topology/booleanTopology.cpp
index 45b933f15..727266e2e 100644
--- a/smp/src/topology/booleanTopology.cpp
+++ b/smp/src/topology/booleanTopology.cpp
@@ -36,6 +36,7 @@ paradiseo::smp::BooleanTopology<TopologyType>::BooleanTopology(unsigned nbIsland
 	TopologyType builder;
 	builder(nbIsland, _matrix);
 }
+
 template <class TopologyType>	
 std::vector<unsigned> paradiseo::smp::BooleanTopology<TopologyType>::getIdNeighbours(unsigned idIsland) const
 {
diff --git a/smp/test/CMakeLists.txt b/smp/test/CMakeLists.txt
index 9e904f991..aca8f9979 100644
--- a/smp/test/CMakeLists.txt
+++ b/smp/test/CMakeLists.txt
@@ -17,7 +17,8 @@ set (TEST_LIST
         t-smpMW_eoEasyPSO
         t-smpMW_eoSyncEasyPSO
         t-smpIsland
-		t-smpTopo)
+		#t-smpTopo
+		)
 
 ######################################################################################
 ### 3) Create each test
diff --git a/smp/test/t-smpIsland.cpp b/smp/test/t-smpIsland.cpp
index fbc2389a9..555650367 100644
--- a/smp/test/t-smpIsland.cpp
+++ b/smp/test/t-smpIsland.cpp
@@ -9,11 +9,11 @@ using namespace std;
 int main(void)
 {
     typedef struct {
-        unsigned popSize = 10;
+        unsigned popSize = 100;
         unsigned tSize = 2;
         double pCross = 0.8;
         double pMut = 0.7;
-        unsigned maxGen = 10;
+        unsigned maxGen = 10000;
     } Param; 
 
     Param param;