Enhance StopWatch

Clean up, comments and enhancements. StopWatch lap() didn't mean lap-time, but elapsed time. Changed meaning to lap-time and added split() for split-time.

maxutils/maxbase/include/maxbase/stopwatch.hh

@@ -20,51 +20,103 @@
 namespace maxbase
 {
 
+/**
+ *   @class Clock
+ *
+ *   MaxScale "standard" std::chrono clock
+ */
 using Clock = std::chrono::steady_clock;
 
-struct Duration : public Clock::duration    // for ADL
+/**
+ *  @class Duration
+ *
+ *  Duration behaves exactly like Clock::duration, but adds ADL and, a
+ *  conveniece constructor and function secs() for seconds as a double.
+ */
+struct Duration : public Clock::duration
 {
     using Clock::duration::duration;
     Duration() = default;
     Duration(Clock::duration d) : Clock::duration(d)
     {
     }
-    Duration(long long l) : Clock::duration(l)
-    {
-    }                                               // FIXME. Get rid of this.
 
+    /** From seconds */
     explicit Duration(double secs) : Duration{rep(secs * period::den / period::num)}
     {
     }
 
+    /** To seconds */
     double secs()
     {
         return std::chrono::duration<double>(*this).count();
     }
 };
 
-typedef std::chrono::time_point<Clock, Duration> TimePoint;
+/**
+ *   @class TimePoint
+ *
+ *   A std::chrono::time_point to go with Clock and Duration.
+ */
+using TimePoint = std::chrono::time_point<Clock, Duration>;
 
+/**
+ *  @class StopWatch
+ *
+ *  Simple stopwatch for measuring time.
+ *
+ *  Example usage:
+ *    auto limit = maxbase::Duration(std::chrono::milliseconds(100));
+ *
+ *    maxbase::StopWatch sw;
+ *    foo();
+ *    auto duration = sw.split();
+ *
+ *    std::cout << "foo duration " << duration << std::endl;
+ *    if (duration > limit)
+ *    {
+ *        maxbase::Duration diff = duration - limit; // no auto, would become Clock::duration.
+ *        std::cerr << "foo exceeded the limit " << limit << " by "  << diff << std::endl;
+ *    }
+ *  Possible output:
+ *    foo duration 100.734ms
+ *    foo exceeded the limit 100ms by 733.636us
+ */
 class StopWatch
 {
 public:
-    // Starts the stopwatch, which is always running.
+    /** Create and start the stopwatch. */
     StopWatch();
-    // Get elapsed time.
-    Duration lap() const;
-    // Get elapsed time, restart StopWatch.
+
+    /** Split time. Overall duration since creation or last restart(). */
+    Duration split() const;
+
+    /** Lap time. Time since last lap() call, or if lap() was not called, creation or last restart(). */
+    Duration lap();
+
+    /** Return split time and restart stopwatch. */
     Duration restart();
 private:
     TimePoint m_start;
+    TimePoint m_lap;
 };
 
-// Returns the value as a double and string adjusted to a suffix like ms for milliseconds.
+/** Returns the duration as a double and string adjusted to a suffix like ms for milliseconds.
+ *  The double and suffix (unit) combination is selected to be easy to read.
+ *  This is for output conveniece. You can always convert a duration to a specific unit:
+ *  long ms {std::chrono::duration_cast<std::chrono::milliseconds>(dur).count()};
+ */
 std::pair<double, std::string> dur_to_human_readable(Duration dur);
 
-// Human readable output. No standard library for it yet.
-std::ostream& operator<<(std::ostream&, Duration dur);
+/** Create a string using dur_to_human_readable, std::ostringstream << d.first << sep << d.second. */
+std::string to_string(Duration dur, const std::string& sep = "");
 
-// TimePoint
-std::string   time_point_to_string(TimePoint tp, const std::string& fmt = "%F %T");
+/** Stream to os << d.first << d.second. Not using to_string(), which would use a default stream. */
+std::ostream& operator<<(std::ostream& os, Duration dur);
+
+/** TimePoint to string, formatted using strftime formats. */
+std::string to_string(TimePoint tp, const std::string& fmt = "%F %T");
+
+/** Stream to std::ostream using to_string(tp) */
 std::ostream& operator<<(std::ostream&, TimePoint tp);
-}   // maxbase
+}