compbench-devel

[Frederic T. <xf...@us...>]

Update of /cvsroot/compbench/CompBenchmarks++/libcompbenchmarks/Plan
In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv2069

Modified Files:
	Plan-Batch.h Plan.h 
Log Message:
For SF's TID #141819 : improving Doxygen documentation.

Index: Plan.h
===================================================================
RCS file: /cvsroot/compbench/CompBenchmarks++/libcompbenchmarks/Plan/Plan.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** Plan.h	21 Aug 2007 19:49:09 -0000	1.10
--- Plan.h	6 Sep 2007 16:51:40 -0000	1.11
***************
*** 36,95 ****
  namespace CBM {
    /** \brief Configure and run benchmarks within specified contexts.
     *  This class manage sets of benchmarks, compiler options and compilers
!    *  to evaluate performances in a convenient way. */
    class Plan {
    protected:
      std::vector<CBM_PB*>                 planBatch;
      
      /** Current iteration.
       *  This value represents the index of the current benchmarking evaluation
!      *  !!!
       */
      int                                  iteration;
      std::string                          filename;
      std::string                          outputDirectory;
      int                                  hostCopied;
      int                                  planCopied;
      int                                  compilerCopied;
  
      virtual CBM_PB *batchForIteration(int *it_in_plan);
  
    public:
      Plan();
  
      virtual int setOutputDirectory(std::string _outputDirectory);
      virtual std::string getOutputDirectory(void);
      virtual int outputDirectoryAdd(CBM::Result *_result);
      virtual int outputDirectoryCopyHost(void);
      virtual int outputDirectoryCopyPlan(void);
      virtual int outputDirectoryCopyCompilers(void);
  
      virtual CBM_PB *addBatch(CBM_PB *_ps);
      virtual int removeBatch(CBM_PB *_ps);
      virtual int removeBatch(std::string _id);
      virtual int batchNumber(void);
  
      virtual CBM_PB *getBatch(std::string _id);
-     virtual CBM_PB *getBatch(int i);
  
  
      virtual int totalIterations(void);
  
      virtual int currentIteration(void);
      virtual class Compiler* currentCompiler(void);
      virtual CBM_OP *currentCompilerOptions(void);
      virtual class Benchmark *currentBenchmark(void);
  
!     /** 0 means end. */
      virtual int nextIteration(int simule = 0);
  
      virtual void stop(void);
      
      class XMLNode *XML(void);
  
      virtual void reset(void);
      virtual int store(std::string _filename = "", int _keepFilename=1);
      virtual int restore(std::string _filename);
  
      virtual ~Plan();
    };
--- 36,263 ----
  namespace CBM {
    /** \brief Configure and run benchmarks within specified contexts.
+    *
     *  This class manage sets of benchmarks, compiler options and compilers
!    *  to evaluate performances in a convenient way.
!    *
!    *  All theses parameters are owned by CBM::PlanBatch instances.
!    */
    class Plan {
    protected:
+     /** List of active CBM::PlanBatch instances.
+      *  \sa iteration
+      *  \sa batchForIteration() */
      std::vector<CBM_PB*>                 planBatch;
      
      /** Current iteration.
       *  This value represents the index of the current benchmarking evaluation
!      *  for the whole Plan.
!      *
!      *  See CBM::PlanBatch::iteration
       */
      int                                  iteration;
+ 
+     /** XML Filename for current plan object. */
      std::string                          filename;
+     /** XML output directory for benchmarking results. */
      std::string                          outputDirectory;
+ 
+     /** 1 if host information XML file has been generated in outputDirectory,
+      *  0 otherwise. */
      int                                  hostCopied;
+ 
+     /** 1 if plan XML file has been generated in outputDirectory,
+      *  0 otherwise. */
      int                                  planCopied;
+ 
+     /** 1 if compiler description XML files have been generated in
+      *  outputDirectory, 0 otherwise. */
      int                                  compilerCopied;
  
+     /** Get batch and its interal iteration index.
+      *
+      *  Method uses iteration variable to do so.
+      *  \param it_in_plan Pointer to integer variable that'll contain batch iteration
+      *  \return Batch on which the it_in_plan has to be applied on
+      */
      virtual CBM_PB *batchForIteration(int *it_in_plan);
  
    public:
+     /** Constructor */
      Plan();
  
+     /** Define output directory.
+      *
+      *  Output directory keeps plan, compilers and host parameters. It also
+      *  contains all XML result files for benchmarks.
+      *
+      *  \param _outputDirectory Directory to use (can be created)
+      *  \return 1 on success, 0 otherwise
+      *  \sa getOutputDirectory() */
      virtual int setOutputDirectory(std::string _outputDirectory);
+ 
+     /** Get output directory.
+      *
+      *  \return Output directory defined or previously stored.
+      *  \sa setOuputDirectory
+      *  \sa outputDirectory */
      virtual std::string getOutputDirectory(void);
+ 
+     /** Store a result object on disk.
+      *
+      *  Stores a XML representation of a benchmark evaluation in the
+      *  output directory.
+      *
+      *  \param _result Result to store
+      *  \return 1 on success, 0 otherwise
+      *  \sa outputDirectory
+      */
      virtual int outputDirectoryAdd(CBM::Result *_result);
+ 
+     /** Copy host information to output directory.
+      *
+      *  First check for file presence, then copy file (host representation).
+      *
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int outputDirectoryCopyHost(void);
+ 
+     /** Copy plan information to output directory.
+      *
+      *  Duplicates plan information into output directory (plan information
+      *  XML file is not supposed to be in output directory; thus copying it
+      *  allows to have whole plan information going together with, for
+      *  instance, XML files describing benchmark results.
+      *
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int outputDirectoryCopyPlan(void);
+ 
+     /** Copy compilers' information to output directory.
+      *
+      *  First check for file presence, then copy file (compilers' XML
+      *  representation).
+      *
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int outputDirectoryCopyCompilers(void);
  
+     /** Add a batch.
+      *
+      *  \param _ps Batch to add in current plan
+      *  \return Pointer to added batch
+      */
      virtual CBM_PB *addBatch(CBM_PB *_ps);
+ 
+     /** Remove a batch.
+      *
+      *  \param _ps Batch to remove from current plan
+      *  \return 1 on success, 0 otherwise
+      *  \sa batchNumber()
+      *  \sa removeBatch(std::string)
+      */
      virtual int removeBatch(CBM_PB *_ps);
+ 
+     /** Remove a batch by its identifier
+      *
+      *  \param _id Identifier of batch to remove from current plan
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int removeBatch(std::string _id);
+ 
+     /** Get batch number
+      *  \return Number of batchs defined.
+      *  \sa getBatch()
+      */
      virtual int batchNumber(void);
  
+     /** Get a batch by its identifier.
+      *  \param _id Batch's identifier
+      *  \return Wanted batch object
+      */
      virtual CBM_PB *getBatch(std::string _id);
  
+     /** Get a batch by its index
+      *  \param i Batch's index
+      *  \return Wanted batch object
+      *  \sa batchNumber
+      */
+     virtual CBM_PB *getBatch(int i);
  
+     /** Get total iterations for plan
+      *  \return Number of total iterations
+      *  \sa iteration */
      virtual int totalIterations(void);
  
+     /** Get current iteration index
+      *  \return Current iteration
+      *  \sa iteration
+      */
      virtual int currentIteration(void);
+ 
+ 
+     /** Get current compiler
+      *  \return Current compiler
+      *  \sa iteration
+      */
      virtual class Compiler* currentCompiler(void);
+ 
+     /** Get current options
+      *  \return Current options
+      *  \sa iteration
+      */
      virtual CBM_OP *currentCompilerOptions(void);
+ 
+     /** Get current benchmark
+      *  \return Current benchmark
+      *  \sa iteration
+      */
      virtual class Benchmark *currentBenchmark(void);
  
!     /** Run an iteration.
!      *
!      *  This method try to benchmark current compiler with current options,
!      *  and current benchmark.
!      *
!      *  \param simule Just display context, don't launch benchmarking.
!      *
!      *  \sa CBM::PlanBatch::currentIteration()
!      *  \return 0 if we've reach the end of the batch, 1 otherwise */
      virtual int nextIteration(int simule = 0);
  
+     /** Stop plan.
+      *
+      *  \sa CBM::PlanBatch::stop()
+      */
      virtual void stop(void);
      
+     /** Get XML representation
+      *  \return XML plan representation */
      class XMLNode *XML(void);
  
+     /** Reset plan.
+      *
+      *  Reset all internal contexts, all call reset() method of each
+      *  defined batch.
+      *
+      *  \sa CBM::PlanBatch::reset()
+      */
      virtual void reset(void);
+ 
+     /** Save context (as XML)
+      *  \param _filename File to use, leave empty for default (previous)
+      *  \param _keepFilename 1 (defaults) to keep the previous name, 0 otherwise
+      *  \return 1 on success, 0 otherwise
+      *  \sa restore()
+      */
      virtual int store(std::string _filename = "", int _keepFilename=1);
+ 
+     /** Restore context (from XML file)
+      *  \param _filename File to use for reading plan parameters
+      *  \return 1 on success, 0 otherwise
+      *  \sa store(std::string, int)
+      */
      virtual int restore(std::string _filename);
  
+     /** Destructor */
      virtual ~Plan();
    };

Index: Plan-Batch.h
===================================================================
RCS file: /cvsroot/compbench/CompBenchmarks++/libcompbenchmarks/Plan/Plan-Batch.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** Plan-Batch.h	1 Aug 2007 19:45:21 -0000	1.5
--- Plan-Batch.h	6 Sep 2007 16:51:40 -0000	1.6
***************
*** 52,126 ****
      
      /** Current iteration.
       *  This value represents the index of the current benchmarking evaluation
!      *  !!!
       */
      int                                  iteration;
  
      virtual int isUnique(class Compiler  *_compiler);
  
!     /** languages */
      virtual int isLanguageCompatibleWithCompilers(std::string _lang);
      virtual int isLanguageCompatibleWithBenchmarks(std::string _lang);
  
      virtual int isUnique(CBM_OS          *_set);
      virtual int isUnique(class Benchmark *_benchmark);
  
      virtual void restoreBenchmarks(class XMLNode *_benchmarksNode);
      virtual void restoreCompilerOptionSet(class XMLNode *_cosNode);
      virtual void restoreCompilers(class XMLNode *_compilersNode);
  
    public:
!     PlanBatch(CBM::Plan *_plan,
  	      std::string _id);
  
      virtual std::string Id(void);
      virtual void setId(std::string _id);
  
      virtual int add(class Compiler        *_compiler);
      virtual int add(CBM_OS                *_set);
      virtual CBM_OP *addOptions(CBM_OS *_set, std::string _id);
  
      virtual int add(class Benchmark       *_benchmark);
  
      virtual int remove(class Compiler     *_compiler);
      virtual int remove(CBM_OS             *_set);
  
      virtual int remove(CBM_OS             *_set,
  		       CBM_OP             *_opt);
  
      virtual int remove(class Benchmark    *_benchmark);
  
      virtual int compilerNumber(void);
      virtual int compilerOptionSetNumber(void);
  
      virtual int compilerOptionsTotalNumber(void);
  
      virtual int benchmarkNumber(void);
  
      virtual class Compiler* getCompiler(int _index);
      virtual CBM_OS *getCompilerOptionSet(int _index);
      virtual CBM_OS *getCompilerOptionSet(std::string id);
  
      virtual CBM_BM *getBenchmark(int _index);
  
      virtual int totalIterations(void);
  
      virtual int currentIteration(void);
      virtual void setIteration(int _it);
  
      virtual class Compiler* currentCompiler(void);
      virtual CBM_OP *currentCompilerOptions(void);
      virtual class Benchmark *currentBenchmark(void);
  
!     /** 0 means end. */
      virtual int nextIteration(int simule = 0);
  
      virtual void stop(int _broadcast);
!     
      class XMLNode *XML(void);
  
      virtual void reset(void);
      virtual int restore(XMLNode *_planRootNode);
  
      virtual ~PlanBatch();
    };
--- 52,326 ----
      
      /** Current iteration.
+      *
       *  This value represents the index of the current benchmarking evaluation
!      *  within the CBM::PlanBatch instance; index is computed according to
!      *  option set number, compiler number, selected benchmarks' number, and
!      *  number of evaluations per benchmarks.
       */
      int                                  iteration;
  
+     /** Detect if a compiler has already been selected.
+      *
+      *  \param _compiler Compiler to check.
+      *  \return 0 if the compiler is already in list, 1 otherwise.
+      */
      virtual int isUnique(class Compiler  *_compiler);
  
!     /** Compiler language compilibility.
!      *
!      *  \param _lang Language (C, C++ at this time)
!      *  \return 1 if all selected compilers are compatible with given language, 0
!      *  otherwise */
      virtual int isLanguageCompatibleWithCompilers(std::string _lang);
+ 
+     /** Benchmark language compilibility.
+      *
+      *  \param _lang Language (C, C++ at this time)
+      *  \return 1 if all selected benchmarks are compatible with given language, 0
+      *  otherwise */
      virtual int isLanguageCompatibleWithBenchmarks(std::string _lang);
  
+     /** Detect if an option set has already been selected.
+      *
+      *  \param _set Option set.
+      *  \return 0 if option set has already been selected, 0 otherwise. */
      virtual int isUnique(CBM_OS          *_set);
+ 
+     /** Detect if a benchmark has already been selected.
+      *
+      *  \param _benchmark Benchmark
+      *  \return 0 if benchmark has already been selected, 0 otherwise. */
      virtual int isUnique(class Benchmark *_benchmark);
  
+     /** Initialize selected benchmarks from XML.
+      *
+      *  \param _benchmarksNode XML node used to initialize selected benchmarks' list */
      virtual void restoreBenchmarks(class XMLNode *_benchmarksNode);
+ 
+     /** Initialize option sets from XML.
+      *
+      *  \param _cosNode XML node used to initialize option sets */
      virtual void restoreCompilerOptionSet(class XMLNode *_cosNode);
+ 
+     /** Initialize compiler list from XML.
+      *
+      *  \param _compilersNode XML node used to initialize compilers' list */
      virtual void restoreCompilers(class XMLNode *_compilersNode);
  
    public:
!     /** Constructor.
!      *  \param _plan Parent plan object
!      *  \param _id   Internal identifier
!      */
!     PlanBatch(CBM::Plan   *_plan,
  	      std::string _id);
  
+     /** Get internal identifier.
+      *  \return Internal identifier for instance (user defined label). */
      virtual std::string Id(void);
+ 
+     /** Set internal identifier.
+      *  \param _id Internal identifier for instance (user defined label). */
      virtual void setId(std::string _id);
  
+ 
+     /** Check and select a compiler.
+      *
+      *  \param _compiler Compiler to be added
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int add(class Compiler        *_compiler);
+ 
+     /** Check and select an option set.
+      *
+      *  \param _set Option set to be added
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int add(CBM_OS                *_set);
+ 
+     /** Add new options.
+      *
+      *  \param _set Option set
+      *  \param _id Internal label (identifier) for new options
+      *
+      *  \return Pointer to options holder
+      */
+ 
      virtual CBM_OP *addOptions(CBM_OS *_set, std::string _id);
  
+     /** Add new benchmark.
+      *
+      * \param _benchmark Benchmark to be added
+      * \return 1 on success, 0 otherwise */
      virtual int add(class Benchmark       *_benchmark);
  
+     /** Remove a compiler.
+      *
+      * \param _compiler Compiler to remove
+      * \return 1 on success, 0 otherwise */
      virtual int remove(class Compiler     *_compiler);
+ 
+     /** Remove an option set.
+      *
+      * \param _set Option set to remove
+      * \return 1 on success, 0 otherwise */
      virtual int remove(CBM_OS             *_set);
  
+     /** Remove options from a set.
+      *
+      * \param _set Option set
+      * \param _opt Options to remove from set
+      * \return 1 on success, 0 otherwise */
      virtual int remove(CBM_OS             *_set,
  		       CBM_OP             *_opt);
  
+     /** Remove a benchmark.
+      *
+      * \param _benchmark Benchmark to remove
+      * \return 1 on success, 0 otherwise */
+ 
      virtual int remove(class Benchmark    *_benchmark);
  
+     /** Get compiler number.
+      *
+      *  Get number of compilers used within batch.
+      *  \return Number of compilers
+      */
      virtual int compilerNumber(void);
+ 
+     /** Get option set number.
+      *
+      *  Get number of option set used within batch.
+      *  \return Number of option set
+      */
      virtual int compilerOptionSetNumber(void);
  
+     /** Get options number.
+      *
+      *  Get total number of options defined in all option set (through
+      *  child CompilerOptions objects).
+      *  \return Number of options
+      */
      virtual int compilerOptionsTotalNumber(void);
  
+     /** Get benchmark number.
+      *
+      *  Get number of benchmarks used within batch.
+      *  \return Number of benchmarks
+      */
      virtual int benchmarkNumber(void);
  
+     /** Get a compiler by its index.
+      *  \param _index Compiler index
+      *  \return Pointer to compiler
+      *  \sa compilerNumber()
+      */
      virtual class Compiler* getCompiler(int _index);
+ 
+     /** Get an option set by its index.
+      *  \param _index Option set index
+      *  \return Pointer to an option set
+      *  \sa compilerOptionSetNumber()
+      */
      virtual CBM_OS *getCompilerOptionSet(int _index);
+ 
+     /** Get an option set by its identifier.
+      *  \param id Option set identifier
+      *  \return Pointer to selected option set
+      */
      virtual CBM_OS *getCompilerOptionSet(std::string id);
  
+     /** Get an benchmark by its index
+      *  \param _index Benchmark's index
+      *  \return Pointer to benchmark object
+      */
      virtual CBM_BM *getBenchmark(int _index);
  
+     /** Get total number of iterations.
+      *  \return Iterations
+      *  \sa iteration
+      */
      virtual int totalIterations(void);
  
+     /** Get current iteration.
+      *  \return Current iteration
+      *  \sa iteration
+      */
      virtual int currentIteration(void);
+ 
+     /** Set current iteration index.
+      *
+      *  This is especialy useful on loading.
+      *
+      *  \param _it (new) current iteration
+      *  \sa restore()
+      *  \sa iteration
+      */
      virtual void setIteration(int _it);
  
+     /** Get current compiler.
+      *  \return Current compiler
+      *  \sa currentIteration()
+      */
      virtual class Compiler* currentCompiler(void);
+ 
+     /** Get current options.
+      *  \return Current options
+      *  \sa currentIteration()
+      */
      virtual CBM_OP *currentCompilerOptions(void);
+ 
+     /** Get current benchmark.
+      *  \return Current benchmark
+      *  \sa currentBenchmark()
+      */
      virtual class Benchmark *currentBenchmark(void);
  
! 
!     /** Run an iteration.
!      *
!      *  This method try to benchmark current compiler with current options,
!      *  and current benchmark.
!      *
!      *  \sa currentCompiler()
!      *  \sa currentCompilerOptions()
!      *  \sa currentBenchmark()
!      *  \param simule set to 1 to not execute benchmark, and just display parameters
!      *  \return 0 if we've reach the end of the batch, 1 otherwise */
      virtual int nextIteration(int simule = 0);
  
+     /** Stop current benchmarking.
+      *
+      *  Initialize internal contexts, and set iteration to 0. This method is
+      *  called on restore() when current and saved contexts differ.
+      *
+      *  \param _broadcast Informs parent CBM::Plan object
+      *  \sa iteration
+      */
      virtual void stop(int _broadcast);
! 
!     /** Get XML representation.
!      *
!      *  This include current iteration.
!      *
!      *  \return XML Patch representation */
      class XMLNode *XML(void);
  
+     /** Reset current benchmarking.
+      *
+      *  Initialize internal contexts, and set iteration to 0. This method is
+      *  called to restart a whole CBM::Plan or CBM::PlanBatch object.
+      *
+      *  \sa iteration
+      */
      virtual void reset(void);
+ 
+     /** Restore instance parameter from XML.
+      *  \param _planRootNode XML representation of a batch
+      *  \return 1 on success, 0 otherwise
+      */
      virtual int restore(XMLNode *_planRootNode);
  
+     /** Destructor */
      virtual ~PlanBatch();
    };