Documentation of serialization, utils/eoTimer and eoPopEvalFunc.

eo/src/eoPopEvalFunc.h

@@ -30,6 +30,13 @@
 #include <eoEvalFunc.h>
 #include <apply.h>
 
+# ifdef WITH_MPI
+#include <mpi/eoMpi.h>
+#include <mpi/eoTerminateJob.h>
+#include <mpi/eoMpiAssignmentAlgorithm.h>
+#include <mpi/eoParallelApply.h>
+# endif // WITH_MPI
+
 /** eoPopEvalFunc: This abstract class is for GLOBAL evaluators
  *    of a population after variation.
  *    It takes 2 populations (typically the parents and the offspring)
@@ -78,12 +85,43 @@ private:
 };
 
 #ifdef WITH_MPI
-// TODO TODOB commenter
+/**
+ * @brief Evaluator of a population of EOT which uses parallelization to evaluate individuals.
+ *
+ * This class implements an instance of eoPopEvalFunc that applies a private eoEvalFunc to
+ * all offspring, but in a parallel way. The original process becomes the central host from a network ("master"), and
+ * other machines disponible in the MPI network ("slaves") are used as evaluators. Population to evaluate is splitted in
+ * little packets of individuals, which are sent to the evaluators, that process the effective call to eval. Once all
+ * the individuals have been evaluated, they are returned to the master. The whole process is entirely invisible to the
+ * eyes of the user, who just has to launch a certain number of processes in MPI so as to have a result.
+ *
+ * The eoEvalFunc is no more directly given, but it is stored in the eo::mpi::ParallelApplyStore, which can be
+ * instanciated if no one is given at construction.
+ *
+ * The use of this class requires the user to have called the eo::mpi::Node::init function, at the beginning of its
+ * program.
+ *
+ * @ingroup Evaluation Parallel
+ *
+ * @author Benjamin Bouvier <benjamin.bouvier@gmail.com>
+ */
 template<class EOT>
 class eoParallelPopLoopEval : public eoPopEvalFunc<EOT>
 {
     public:
-        /** Ctor: set value of embedded eoEvalFunc */
+        /**
+         * @brief Constructor which creates the job store for the user.
+         *
+         * This constructor is the simplest to use, as it creates the store used by the parallel job, for the user.
+         * The user just precises the scheduling algorithm, the rank of the master and then gives its eval function and
+         * the size of a packet (how many individuals should be in a single message to evaluator).
+         *
+         * @param _assignAlgo The scheduling algorithm used to give orders to evaluators.
+         * @param _masterRank The MPI rank of the master.
+         * @param _eval The evaluation functor used to evaluate each individual in the population.
+         * @param _packetSize The number of individuals to send in one message to evaluator, and which are evaluated at
+         * a time.
+         */
         eoParallelPopLoopEval(
                 // Job parameters
                 eo::mpi::AssignmentAlgorithm& _assignAlgo,
@@ -94,12 +132,21 @@ class eoParallelPopLoopEval : public eoPopEvalFunc<EOT>
                 ) :
             assignAlgo( _assignAlgo ),
             masterRank( _masterRank ),
-            needToDeleteStore( true )
+            needToDeleteStore( true ) // we used new, we'll have to use delete (RAII)
         {
-            // FIXME memory leak because of new.
             store = new eo::mpi::ParallelApplyStore<EOT>( _eval, _masterRank, _packetSize );
         }
 
+        /**
+         * @brief Constructor which allows the user to customize its job store.
+         *
+         * This constructor allows the user to customize the store, for instance by adding wrappers and other
+         * functionnalities, before using it for the parallelized evaluation.
+         *
+         * @param _assignAlgo The scheduling algorithm used to give orders to evaluators.
+         * @param _masterRank The MPI rank of the master.
+         * @param _store Pointer to a parallel eval store given by the user.
+         */
         eoParallelPopLoopEval(
                 // Job parameters
                 eo::mpi::AssignmentAlgorithm& _assignAlgo,
@@ -109,37 +156,57 @@ class eoParallelPopLoopEval : public eoPopEvalFunc<EOT>
             assignAlgo( _assignAlgo ),
             masterRank( _masterRank ),
             store( _store ),
-            needToDeleteStore( false )
+            needToDeleteStore( false ) // we haven't used new for creating store, we don't care if we have to delete it (RAII).
         {
             // empty
         }
 
+        /**
+         * @brief Default destructor. Sends a message to all evaluators indicating that the global loop (eoEasyEA, for
+         * instance) is over.
+         */
         ~eoParallelPopLoopEval()
         {
+            // Only the master has to send the termination message
             if( eo::mpi::Node::comm().rank() == masterRank )
             {
                 eo::mpi::EmptyJob job( assignAlgo, masterRank );
                 job.run();
             }
 
+            // RAII
             if( needToDeleteStore )
             {
                 delete store;
             }
         }
 
-        /** Do the job: simple loop over the offspring */
+        /**
+         * @brief Parallel implementation of the operator().
+         *
+         * @param _parents Population of parents (ignored).
+         * @param _offspring Population of children, which will be evaluated.
+         */
         void operator()( eoPop<EOT> & _parents, eoPop<EOT> & _offspring )
         {
             (void)_parents;
-            parallelApply<EOT>(_offspring, assignAlgo, masterRank, *store);
+            // Reinits the store and the scheduling algorithm
+            store->data( _offspring );
+            assignAlgo.reinit( _offspring.size() );
+            // Effectively launches the job.
+            eo::mpi::ParallelApply<EOT> job( assignAlgo, masterRank, *store );
+            job.run();
         }
 
     private:
+        // Scheduling algorithm
         eo::mpi::AssignmentAlgorithm & assignAlgo;
+        // Master MPI rank
         int masterRank;
 
+        // Store
         eo::mpi::ParallelApplyStore<EOT>* store;
+        // Do we have to delete the store by ourselves ?
         bool needToDeleteStore;
 };
 #endif