Documentation of serialization, utils/eoTimer and eoPopEvalFunc.

eo/src/apply.h

@@ -33,12 +33,6 @@
 #include <vector>
 #include <omp.h>
 
-# ifdef WITH_MPI
-# include <mpi/eoMpi.h>
-# include <mpi/eoMultiParallelApply.h>
-# include <mpi/eoTerminateJob.h>
-# endif // WITH_MPI
-
 /**
   Applies a unary function to a std::vector of things.
 
@@ -85,21 +79,6 @@ void apply(eoUF<EOT&, void>& _proc, std::vector<EOT>& _pop)
 #endif // !_OPENMP
 }
 
-#ifdef WITH_MPI
-template<class EOT>
-void parallelApply(
-        std::vector<EOT>& _pop,
-        eo::mpi::AssignmentAlgorithm& _algo,
-        int _masterRank,
-        eo::mpi::ParallelApplyStore<EOT> & _store )
-{
-    _store.data( _pop );
-    _algo.reinit( _pop.size() );
-    eo::mpi::ParallelApply<EOT> job( _algo, _masterRank, _store );
-    job.run();
-}
-#endif
-
 /**
   This is a variant of apply<EOT> which is called in parallel
   thanks to OpenMP.

eo/src/eoEasyEA.h

@@ -37,8 +37,6 @@
 #include <eoMergeReduce.h>
 #include <eoReplacement.h>
 
-
-
 template <class EOT> class eoIslandsEasyEA ;
 
 template <class EOT> class eoDistEvalEasyEA ;
@@ -247,7 +245,6 @@ template<class EOT> class eoEasyEA: public eoAlgo<EOT>
     virtual void operator()(eoPop<EOT>& _pop)
     {
 
-        eo::log << "[EasyEA] Call to operator()" << std::endl;
         if (isFirstCall)
         {
             size_t total_capacity = _pop.capacity() + offspring.capacity();
@@ -256,39 +253,26 @@ template<class EOT> class eoEasyEA: public eoAlgo<EOT>
             isFirstCall = false;
         }
 
-    // TODO TODOB delete all log traces
-    std::cout << "[EasyEA] After is first call." << std::endl;
-
         eoPop<EOT> empty_pop;
-        std::cout << "[EasyEA] After empty_pop." << std::endl;
-
-      popEval(empty_pop, _pop); // A first eval of pop.
-        std::cout << "[EasyEA] After pop_eval." << std::endl;
 
         do
         {
             try
             {
-        std::cout << "[EasyEA] Beginning try." << std::endl;
                 unsigned pSize = _pop.size();
-        std::cout << "[EasyEA] psize determinated." << std::endl;
+
                 offspring.clear(); // new offspring
-        std::cout << "[EasyEA] offspring cleared." << std::endl;
 
                 breed(_pop, offspring);
 
-        std::cout << "[EasyEA] After breed, evaluating pop." << std::endl;
                 popEval(_pop, offspring); // eval of parents + offspring if necessary
 
-        std::cout << "[EasyEA] After evaluation, replacing pop." << std::endl;
                 replace(_pop, offspring); // after replace, the new pop. is in _pop
-        std::cout << "[EasyEA] After replacing, continuator." << std::endl;
 
                 if (pSize > _pop.size())
                     throw std::runtime_error("Population shrinking!");
                 else if (pSize < _pop.size())
                     throw std::runtime_error("Population growing!");
-
             }
             catch (std::exception& e)
             {

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

eo/src/serial/Array.cpp

@@ -1,8 +1,28 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # include "Array.h"
 
 namespace eoserial
 {
-
     std::ostream& Array::print( std::ostream& out ) const
     {
         out << "[";

eo/src/serial/Array.h

@@ -1,14 +1,32 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_ARRAY_H__
 # define __EOSERIAL_ARRAY_H__
 
 # include <vector>
-# include <iostream>
 
 # include "Entity.h"
 # include "Serializable.h"
-
 # include "Object.h"
-# include "String.h"
 
 namespace eoserial
 {
@@ -21,6 +39,7 @@ class Array;
      * These are put here to avoid instead of including the file Utils.h, which would
      * cause a circular inclusion.
      */
+
     template< class T >
         void unpack( const Array & array, unsigned int index, T & value );
 
@@ -33,6 +52,8 @@ void unpackArray( const Array & array, unsigned int index, Container & container
      * @brief Represents a JSON array.
      *
      * Wrapper for an array, so as to be used as a JSON object.
+     *
+     * @ingroup Serialization
      */
     class Array : public eoserial::Entity, public std::vector< eoserial::Entity* >
     {

eo/src/serial/Entity.h

@@ -1,9 +1,42 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_ENTITY_H__
 # define __EOSERIAL_ENTITY_H__
 
-# include <iostream>
+# include <iostream> // ostream
-# include <sstream>
 
+/**
+ * @brief Contains all the necessary entities to serialize eo objects into JSON objects.
+ *
+ * Allows serialization from user objects into JSON objects, if they implement the interface
+ * eoserial::Serializable or eoserial::Persistent. The following user objects can be serialized:
+ * - primitive types (int, std::string, ...), in particular every type that can be written into a
+ *   std::stringstream.
+ * - objects which implement eoserial::Serializable.
+ * - array of serializable things (primitive or serializable objects).
+ *
+ * @ingroup Utilities
+ * @defgroup Serialization Serialization helpers
+ */
 namespace eoserial
 {
 
@@ -12,6 +45,8 @@ namespace eoserial
  *
  * This class represents a JSON entity, which can be JSON objects,
  * strings or arrays. It is the base class for the JSON hierarchy.
+ *
+ * @ingroup Serialization
  */
 class Entity
 {

eo/src/serial/Object.cpp

@@ -1,10 +1,30 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # include "Object.h"
 
 using namespace eoserial;
 
 namespace eoserial
 {
-
     std::ostream& Object::print( std::ostream& out ) const
     {
         out << '{';

eo/src/serial/Object.h

@@ -1,21 +1,42 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_OBJECT_H__
 # define __EOSERIAL_OBJECT_H__
 
 # include <map>
 # include <string>
-# include <sstream>
 
 # include "Entity.h"
 # include "Serializable.h"
 
 namespace eoserial
 {
-
     /**
      * @brief JSON Object
      *
      * This class represents a JSON object, which is basically a dictionnary
      * of keys (strings) and values (JSON entities).
+     *
+     * @ingroup Serialization
      */
     class Object : public eoserial::Entity, public std::map< std::string, eoserial::Entity* >
     {

eo/src/serial/Parser.cpp

@@ -1,7 +1,25 @@
-# include <map>
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # include <string>
-# include <sstream>
-# include <vector>
 
 # include "Parser.h"
 

eo/src/serial/Parser.h

@@ -1,3 +1,24 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_PARSER_H__
 # define __EOSERIAL_PARSER_H__
 
@@ -6,6 +27,8 @@
 # include "Object.h"
 
 /**
+ * @file Parser.h
+ *
  * This file contains a tiny JSON parser used in DAE. This parser just handles 
  * a subset of JSON grammar, with the following restrictions :
  * - all strings must be surrounded by double quotes.
@@ -26,6 +49,8 @@ namespace eoserial
  * This parser does just retrieve values and does NOT check the structure of
  * the input. This implies that if the input is not correct, the result is undefined
  * and can result to a failure on execution.
+ *
+ * @ingroup Serialization
  */
 class Parser
 {

eo/src/serial/Serializable.h

@@ -1,16 +1,36 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_SERIALIZABLE_H__
 # define __EOSERIAL_SERIALIZABLE_H__
 
-# include <string>
-
 namespace eoserial
 {
-
     class Object; // to avoid recursive inclusion with JsonObject
 
     /**
      * @brief Interface showing that object can be written to a eoserial type
      * (currently JSON).
+     *
+     * @ingroup Serialization
      */
     class Printable
     {
@@ -27,6 +47,8 @@ public:
      * from an input).
      *
      * Note : Persistent objects should have a default non-arguments constructor.
+     *
+     * @ingroup Serialization
      */
     class Persistent : public Printable
     {

eo/src/serial/String.cpp

@@ -1,3 +1,24 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # include "String.h"
 
 namespace eoserial

eo/src/serial/String.h

@@ -1,3 +1,24 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_STRING_H__
 # define __EOSERIAL_STRING_H__
 
@@ -9,11 +30,12 @@
 
 namespace eoserial
 {
-
     /**
      * @brief JSON String
      *
      * Wrapper for string, so as to be used as a JSON object.
+     *
+     * @ingroup Serialization
      */
     class String : public eoserial::Entity, public std::string
     {
@@ -26,7 +48,7 @@ class String : public eoserial::Entity, public std::string
             String( const std::string& str ) : std::string( str ) {}
 
             /**
-         * @brief Ctor used only on parsing.
+             * @brief Ctor used only when parsing.
              */
             String( ) {}
 

eo/src/serial/Utils.h

@@ -1,3 +1,24 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_UTILS_H__
 # define __EOSERIAL_UTILS_H__
 
@@ -7,7 +28,7 @@
 
 namespace eoserial
 {
-    /*****************************
+    /* ***************************
      * DESERIALIZATION FUNCTIONS *
      *****************************
     These functions are useful for casting eoserial::objects into simple, primitive
@@ -54,7 +75,7 @@ namespace eoserial
         static_cast<Array*>( array[ index ] )->deserialize< Container, UnpackAlgorithm >( container );
     }
 
-    /*******************************
+    /* *****************************
      *** SERIALIZATION FUNCTIONS ***
      *******************************
      These functions are useful for casting classic objects and 

eo/src/serial/eoSerial.h

@@ -1,3 +1,24 @@
+/*
+(c) Thales group, 2012
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
 # ifndef __EOSERIAL_HEADERS__
 # define __EOSERIAL_HEADERS__
 

eo/src/utils/eoParallel.cpp

@@ -37,7 +37,7 @@ eoParallel::eoParallel() :
     _nthreads( 0, "parallelize-nthreads", "Define the number of threads you want to use, nthreads = 0 means you want to use all threads available", '\0' ),
     _enableResults( false, "parallelize-enable-results", "Enable the generation of results", '\0' ),
     _doMeasure( false, "parallelize-do-measure", "Do some measures during execution", '\0' ),
-    _packetSize( 1U, "parallelize-packet-size", "Number of elements which should be sent at a time during a parallel evaluation based on message passing.", '\0'),
+    _packetSize( 1U, "parallelize-packet-size", "Number of elements which should be sent in a single message during a parallel evaluation based on message passing.", '\0'),
     _t_start(0)
 {
 }

eo/src/utils/eoParallel.h

@@ -21,7 +21,6 @@ Contact: http://eodev.sourceforge.net
 
 Authors:
     Caner Candan <caner.candan@thalesgroup.com>
-
 */
 
 /** @defgroup Parallel Parallel

eo/src/utils/eoTimer.h

@@ -1,38 +1,84 @@
-# ifndef __TIMER_H__
+/*
-# define __TIMER_H__
+(c) Thales group, 2012
 
-# include <sys/time.h>
+    This library is free software; you can redistribute it and/or
-# include <sys/resource.h>
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation;
+    version 2 of the License.
 
-# include <vector>
+    This library is distributed in the hope that it will be useful,
-# include <map>
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
 
-# include "utils/eoParallel.h"
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+Contact: http://eodev.sourceforge.net
+
+Authors:
+    Benjamin Bouvier <benjamin.bouvier@gmail.com>
+*/
+# ifndef __EO_TIMER_H__
+# define __EO_TIMER_H__
+
+# include <sys/time.h> // time()
+# include <sys/resource.h> // rusage()
+
+# include <vector> // std::vector
+# include <map> // std::map
+
+# include "utils/eoParallel.h" // eo::parallel
 
 # ifdef WITH_MPI
+// For serialization purposes
 # include <boost/serialization/access.hpp>
 # include <boost/serialization/vector.hpp>
 # include <boost/serialization/map.hpp>
 # endif
 
-// TODO TODOB commenter
+/**
+ * @brief Timer allowing to measure time between a start point and a stop point.
+ *
+ * This timer allows the user to measure user time, system time and wallclock time
+ * between two points. Basically, user time is time spent in developer code ; system
+ * time is time spent during the IO wait and system calls ; wallclock is the difference
+ * of time we could observe by measuring time with a watch.
+ *
+ * @ingroup Utilities
+ */
 class eoTimer
 {
     public:
 
+        /**
+         * @brief Default ctor. Begins all the timers.
+         */
         eoTimer()
-        {
-            restart();
-        }
-
-        void restart()
         {
             uuremainder = 0;
             usremainder = 0;
+            restart();
+        }
+
+        /**
+         * @brief Restarts all the timers and launch the measure.
+         */
+        void restart()
+        {
             wc_start = time(NULL);
             getrusage( RUSAGE_SELF, &_start );
         }
 
+        /**
+         * @brief Measures the user time spent since the last restart().
+         *
+         * If the number of elapsed seconds is zero, the spent milliseconds are
+         * added to a remainder. If the remainder exceeds one second, it is
+         * added to the number of elapsed seconds.
+         *
+         * @return Number of seconds elapsed in user space.
+         */
         long int usertime()
         {
             struct rusage _now;
@@ -44,12 +90,21 @@ class eoTimer
                 if( uuremainder > 1000000)
                 {
                     ++result;
-                    uuremainder = 0;
+                    uuremainder -= 1000000;
                 }
             }
             return result;
         }
 
+        /**
+         * @brief Measures the system time spent since the last restart().
+         *
+         * If the number of elapsed seconds is zero, the spent milliseconds are
+         * added to a remainder. If the remainder exceeds one second, it is
+         * added to the number of elapsed seconds.
+         *
+         * @return Number of seconds elapsed in system (kernel) space.
+         */
         long int systime()
         {
             struct rusage _now;
@@ -61,28 +116,90 @@ class eoTimer
                 if( usremainder > 1000000)
                 {
                     ++result;
-                    usremainder = 0;
+                    usremainder -= 1000000;
                 }
             }
             return result;
         }
 
+        /**
+         * @brief Measures the wallclock time spent since the last restart().
+         *
+         * @return Number of seconds elapsed, as a double.
+         */
         double wallclock()
         {
             return std::difftime( std::time(NULL) , wc_start );
         }
 
     protected:
+        // Structure used to measure user and system time.
         struct rusage _start;
+        // Remainder (in milliseconds) for user time.
         long int uuremainder;
+        // Remainder (in milliseconds) for system time.
         long int usremainder;
+        // Structure used to measure wallclock time.
         time_t wc_start;
 };
 
+/**
+ * @brief Registers a group of statistics, each statistic corresponding to user, system and wallclock times distribution.
+ *
+ * This class helps the user to measure time in different parts of an application. A name is associated to a statistic,
+ * on each call to start() and stop() for this name, a new number is added to the statistic, for each of the three
+ * measured times.
+ *
+ * The statistics are only registered if the option "--parallelized-do-measure" is set to true, which can be checked
+ * thanks to global object eo::parallel.
+ *
+ * This shows how the eoTimerStat can be used :
+ * @code
+ * eoTimerStat timerStat;
+ * timerStat.start("first_point");
+ * for( int i = 0; i < 1000; ++i )
+ * {
+ *   timerStat.start("single_computation");
+ *   single_computation( i );
+ *   timerStat.stop("single_computation");
+ * }
+ * // After this loop, timerStat contains a statistic of key "single_computation" which contains 1000 measures for
+ * // each type of time.
+ * timerStat.stop("first_point");
+ * // After this line, timerStat contains another statistic of key "first_point" which counted the duration of the
+ * // whole loop.
+ *
+ * int singleComputationUsertimeMean = 0;
+ * for( int i = 0; i < 1000; ++i )
+ * {
+ *      singleComputationUsertimeMean += timerStat.stats()["single_computation"].utime[i];
+ * }
+ * std::cout << "Mean of user time spent in single computation: " << singleComputationUsertimeMean / 1000. << std::endl;
+ * @endcode
+ *
+ * When using MPI, these statistics can be readily be serialized, so as to be sent over a network, for instance.
+ *
+ * Implementation details: this eoTimerStat is in fact a map of strings (key) / Stat (value). Stat is an internal
+ * structure directly defined in the class, which contains three vectors modeling the distributions of the different
+ * types of elapsed times. Another map of strings (key) / eoTimer (value) allows to effectively retrieve the different
+ * times. The struct Stat will be exposed to client, which will use its members ; however,
+ * the client doesn't have anything to do directly with the timer, that's why the two maps are splitted.
+ *
+ * @ingroup Utilities
+ */
 class eoTimerStat
 {
     public:
 
+        /**
+         * @brief Statistic related to a key (name).
+         *
+         * This structure is the value in the map saved in the eoTimerStat. It contains the statistic bound to a key,
+         * which are the user time distribution, the system time distribution and the wallclock time distribution, as
+         * std::vector s.
+         *
+         * It can readily be serialized with boost when compiling with mpi.
+         */
         struct Stat
         {
             std::vector<long int> utime;
@@ -93,7 +210,8 @@ class eoTimerStat
             friend class boost::serialization::access;
 
             /**
-             * Serializes the statistique in a boost archive (useful for boost::mpi)
+             * Serializes the single statistic in a boost archive (useful for boost::mpi).
+             * Just serializes the 3 vectors.
              */
             template <class Archive>
                 void serialize( Archive & ar, const unsigned int version )
@@ -109,7 +227,8 @@ class eoTimerStat
         friend class boost::serialization::access;
 
         /**
-             * Serializes the map of statistics in a boost archive (useful for boost::mpi)
+         * Serializes the timerStat object in a boost archive (useful for boost::mpi).
+         * Just serializes the map.
          */
         template <class Archive>
             void serialize( Archive & ar, const unsigned int version )
@@ -119,6 +238,14 @@ class eoTimerStat
             }
 # endif
 
+        /**
+         * @brief Starts a new measure for the given key.
+         *
+         * This is only performed if parallel.doMeasure() is true, which is equivalent to the fact that
+         * parser found "--parallel-do-measure=1" in command line args.
+         *
+         * @param key The key of the statistic.
+         */
         void start( const std::string & key )
         {
             if( eo::parallel.doMeasure() )
@@ -127,6 +254,16 @@ class eoTimerStat
             }
         }
 
+        /**
+         * @brief Stops the mesure for the given key and saves the elapsed times.
+         *
+         * Must follow a call of start with the same key.
+         *
+         * This is only performed if parallel.doMeasure() is true, which is equivalent to the fact that
+         * parser found "--parallel-do-measure=1" in command line args.
+         *
+         * @param key The key of the statistic.
+         */
         void stop( const std::string& key )
         {
             if( eo::parallel.doMeasure() )
@@ -139,13 +276,18 @@ class eoTimerStat
             }
         }
 
-        std::map< std::string, Stat > stats()
+        /**
+         * @brief Getter for the statistics map.
+         */
+        std::map< std::string, Stat >& stats()
         {
             return _stats;
         }
 
     protected:
+        // Statistics map: links a key (string) to a statistic.
         std::map< std::string, Stat > _stats;
+        // Timers map: links a key to its timer.
         std::map< std::string, eoTimer > _timers;
 };