\section*{Summary}
This document describes a practical toolkit to evaluate the status of code. It
can be used to create programs that measure performance, known as benchmarks,
and other various tests, execute them, and analyze their results. With little
effort a user of this toolkit can detect inefficiencies, bottlenecks, and loss
of functionality or performance degradation, compare various techniques,
algorithms, and different implementations, and measure progress. A user, can
then, present the results in a comprehensible way. The information produced
also includes the precise description of the execution environment to allow
the reproduction of the results.

% \subsection*{Concepts}
% \subsection*{Classes}
% \subsection*{Functions}

\begin{ccRefConcept}{Benchable}

\ccCreationVariable{benchable} 

\ccCreation
% =========
\ccConstructor{Benchable();}{default constructor.}

\ccOperations
% ===========
\ccMethod{void init(void);}{%
  this function is invoked once before the function that tests target
  operation is invoked. It is used to initialize all the data members that
  are operands consumed by the target operation. This allows for accurate
  measure of the target-operation performance, through timing of the function
  that performs the target operation.}
  
\ccMethod{void clean(void);}{%
  this function is invoked once after the function that tests the target
  operation returns. It is used to clean up the data members in general and
  the results in particular produced by the target operation.}
  
\ccMethod{void op(void);}{%this function performs the target operation
  repeatedly in loop constrained, either by a maximum number of repetitions,
  or by by a limit on the time period alloted for the target operation,
  depending on the bench configuration.}

\ccMethod{void sync(void);}{%
  this function synchronizes between the target operation and the measure of
  its time consumption. It is called once after initialization and before the
  starting time is sampled, and once again after the target operation is
  performed in a loop and before the ending time is sampled. In many cases
  the \ccc{sync} function is empty, as there is no need to synchronize
  anything. On the other hand, suppose that the performance of a sequence of
  commands in pipeline architecture is to be measured. In this case the
  \ccc{sync} function can be used to flush the pipeline and force all pending
  commands to complete before the ending time is sampled. This situation
  manifests itself when the performance of some {\textbf openGl} (see cite)
  commands is to be measured. The \ccc{sync} function can be implemented to
  call {\textbf glFlush} to cause all issued commands trapped in intermediate
  buffers of the pipeline to be executed as quickly as they are accepted by
  the actual rendering engine before they are assumed to complete.}

\end{ccRefConcept}

\begin{ccRefClass}{Benchmark}

\ccDefinition
% ===========
\ccRefName{} is a utility class that performs the bench. The benchmark is
configured during construction of the \ccc{Bench} class or through
some modifiers.

\ccInclude{CGAL/Benchmark/Benchmark.hpp}

% \ccInheritsFrom
  
\ccCreationVariable{bench}

\ccCreation
% =========  
\ccConstructor{Bench<Benchable>(std::string name = "",
                                int seconds = 1,
				bool print_header = true);}
  {constructs an object of the type \ccc{Benchmark}.}

\ccModifiers
% ==========
\ccMethod{void set_iterations(unsigned int iterations);}{}
  
\ccMethod{void set_seconds(unsigned int seconds);}{}
  
\ccMethod{void set_samples(unsigned int samples);}{}

\ccQueryFunctions
% ===============
\ccMethod{unsigned int iterations() const;}{}

\ccMethod{unsigned int seconds() const;}{}
  
\ccMethod{unsigned int samples() const;}{}
  
\ccMethod{Benchable & benchable();}{}

\ccMethod{void print_results();}{}

\ccMethod{void operator()();}{}
  
\end{ccRefClass}

\begin{ccRefClass}{Option_parser}

\ccDefinition
% ===========

\ccInclude{CGAL/Benchmark/Option_parser.hpp}

% \ccInheritsFrom
  
\ccCreationVariable{option_parser}

\ccCreation
% =========  
\ccConstructor{Option_parser(int argc, char * argv[]);}
  {constructs an instance of the \ccc{Option_parser} class.}

% \ccModifiers

\ccQueryFunctions
% ===============  
\ccMethod{unsigned int samples() const;}{}
  
\ccMethod{unsigned int iterations() const;}{}
  
\ccMethod{int seconds() const;}{}

\ccMethod{bool do_print_header() const;}{}
  
\ccMethod{int field_width(Field_id) const;}{}
  
\end{ccRefClass}
