Changeset 1851:78b5ea23f0f1 in lemon-0.x

Timestamp:

12/06/05 19:44:26 (18 years ago)

Author:

Alpar Juttner

Branch:

default

Phase:

public

Convert:

svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk@2419

Message:

Doc improvements

Location:

lemon

Files:

• counter.h (modified) (1 diff)
• time_measure.h (modified) (8 diffs)

lemon/counter.h

@@ -96 +96 @@
   ///or decrement the counter using operator++ and operator--.
   ///A report is automatically printed on destruction.
+  ///\todo More doc
   class Counter 
   {

lemon/time_measure.h

@@ -45 +45 @@
   /// they can be pushed to a stream.
   ///
-  /// In most cases, perhaps \ref Timer class is what you want to use instead.
+  /// In most cases, perhaps the \ref Timer or the \ref TimeReport
+  /// class is what you want to use instead.
   ///
   ///\author Alpar Juttner
@@ -194 +195 @@
   }
   
+  ///Prints the time counters
+
+  ///Prints the time counters in the following form:
+  ///
+  /// <tt>u: XX.XXs s: XX.XXs cu: XX.XXs cs: XX.XXs real: XX.XXs</tt>
+  ///
+  /// where the values are the
+  /// \li \c u: user cpu time,
+  /// \li \c s: system cpu time,
+  /// \li \c cu: user cpu time of children,
+  /// \li \c cs: system cpu time of children,
+  /// \li \c real: real time.
+  /// \relates TimeStamp
+  inline std::ostream& operator<<(std::ostream& os,const TimeStamp &t)
+  {
+    long cls = sysconf(_SC_CLK_TCK);
+    os << "u: " << double(t.getTms().tms_utime)/cls <<
+      "s, s: " << double(t.getTms().tms_stime)/cls <<
+      "s, cu: " << double(t.getTms().tms_cutime)/cls <<
+      "s, cs: " << double(t.getTms().tms_cstime)/cls <<
+      "s, real: " << t.realTime() << "s";
+    return os;
+  }
+
   ///Class for measuring the cpu time and real time usage of the process
 
@@ -230 +255 @@
   ///distorted results.
   ///
-  ///The \ref Timer also counts the number of \ref start()
-  ///executions, and is stops only after the same amount (or more)
-  ///\ref stop() "stop()"s. This can be useful e.g. to compute the running time
-  ///of recursive functions.
+  ///\note If you want to measure the running time of the execution of a certain
+  ///function, consider the usage of \ref TimeReport instead.
   ///
   ///\todo This shouldn't be Unix (Linux) specific.
+  ///\sa TimeReport
   ///
   ///\author Alpar Juttner
@@ -253 +277 @@
     Timer(bool run=true) :_running(run) {_reset();}
 
-    ///Computes the ellapsed time
-
-    ///This conversion computes the ellapsed time
+    ///\name Control the state of the timer
+    ///Basically a Timer can be either running or stopped,
+    ///but it provides a bit finer control on the execution.
+    ///The \ref Timer also counts the number of \ref start()
+    ///executions, and is stops only after the same amount (or more)
+    ///\ref stop() "stop()"s. This can be useful e.g. to compute the running time
+    ///of recursive functions.
     ///
-    operator TimeStamp () const
-    {
-      TimeStamp t;
-      t.stamp();
-      return _running?t-start_time:start_time;
-    }
+
+    ///@{
 
     ///Reset and stop the time counters
@@ -353 +377 @@
     }
     
+    ///@}
+
+    ///\name Query Functions for the ellapsed time
+
+    ///@{
+
     ///Gives back the ellapsed user time of the process
     double userTime() const
@@ -378 +408 @@
       return operator TimeStamp().realTime();
     }
-
+    ///Computes the ellapsed time
+
+    ///This conversion computes the ellapsed time, therefore you can print
+    ///the ellapsed time like this.
+    ///\code
+    ///  Timer T;
+    ///  doSomething();
+    ///  std::cout << T << '\n';
+    ///\endcode
+    operator TimeStamp () const
+    {
+      TimeStamp t;
+      t.stamp();
+      return _running?t-start_time:start_time;
+    }
+
+
+    ///@}
   };
 
@@ -384 +431 @@
 
   ///Same as \ref Timer but prints a report on destruction.
-  ///\todo Untested
+  ///This example shows its usage.
+  ///\code
+  ///  void myAlg(ListGraph &g,int n)
+  ///  {
+  ///    TimeReport TR("Running time of myAlg: ");
+  ///    ... //Here comes the algorithm
+  ///  }
+  ///\endcode
+  ///
+  ///\sa Timer
+  ///\sa NoTimeReport
+  ///\todo There is no test case for this
   class TimeReport : public Timer 
   {
@@ -391 +449 @@
   public:
     ///\e
-    
-    TimeReport(std::string title,std::ostream &os,bool run) 
+
+    ///\param title This text will be printed before the ellapsed time.
+    ///\param os The stream to print the report to.
+    ///\param run Sets whether the timer should start immediately.
+
+    TimeReport(std::string title,std::ostream &os=std::cerr,bool run=true) 
       : Timer(run), _title(title), _os(os){}
+    ///\e Prints the ellapsed time on destruction.
     ~TimeReport() 
     {
-      _os << _title << this << std::endl;
+      _os << _title << *this << std::endl;
     }
   };
       
-  ///Prints the time counters
-
-  ///Prints the time counters in the following form:
-  ///
-  /// <tt>u: XX.XXs s: XX.XXs cu: XX.XXs cs: XX.XXs real: XX.XXs</tt>
-  ///
-  /// where the values are the
-  /// \li \c u: user cpu time,
-  /// \li \c s: system cpu time,
-  /// \li \c cu: user cpu time of children,
-  /// \li \c cs: system cpu time of children,
-  /// \li \c real: real time.
-  /// \relates TimeStamp
-  inline std::ostream& operator<<(std::ostream& os,const TimeStamp &t)
-  {
-    long cls = sysconf(_SC_CLK_TCK);
-    os << "u: " << double(t.getTms().tms_utime)/cls <<
-      "s, s: " << double(t.getTms().tms_stime)/cls <<
-      "s, cu: " << double(t.getTms().tms_cutime)/cls <<
-      "s, cs: " << double(t.getTms().tms_cstime)/cls <<
-      "s, real: " << t.realTime() << "s";
-    return os;
-  }
-
-  
+  ///'Do nothing' version of \ref TimeReport
+
+  ///\sa TimeReport
+  ///
+  class NoTimeReport
+  {
+  public:
+    ///\e
+    NoTimeReport(std::string title,std::ostream &os=std::cerr,bool run=true) {}
+    ///\e Do nothing.
+    ~NoTimeReport() {}
+
+    operator TimeStamp () const { return TimeStamp(); }
+    void reset() {}
+    void start() {}
+    void stop() {}
+    void halt() {} 
+    int running() { return 0; }
+    void restart() {}
+    double userTime() const { return 0; }
+    double systemTime() const { return 0; }
+    double cUserTime() const { return 0; }
+    double cSystemTime() const { return 0; }
+    double realTime() const { return 0; }
+  };
+      
   ///Tool to measure the running time more exactly.