core/library/timely/time_stamp.h

   1 #ifndef TIME_STAMP_CLASS
   2 #define TIME_STAMP_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : time_stamp                                                        *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1995-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/contracts.h>
  20 #include <basis/definitions.h>
  21
  22 // forward.
  23 class rollover_record;
  24 struct timeval;
  25
  26 namespace timely {
  27
  28 //! Represents a point in time relative to the operating system startup time.
  29 /*!
  30   This duration is measured in milliseconds.  This class provides a handy way
  31   of measuring relative durations at the millisecond time scale.
  32   Unfortunately, operating systems that reckon their millisecond uptime in
  33   32 bit integers will suffer from a rollover problem every 49 days or so,
  34   but this class corrects this issue.
  35 */
  36
  37 class time_stamp : public virtual basis::orderable
  38 {
  39 public:
  40   typedef double time_representation;
  41     //!< the representation of time for this universe, measured in milliseconds.
  42
  43   time_stamp();
  44     //!< creates a time_stamp containing the current time.
  45
  46   time_stamp(time_representation offset);
  47     //!< creates a stamp after the current time by "offset" milliseconds.
  48     /*!< negative offsets are allowed, in which case the stamp will be
  49     prior to the current time. */
  50
  51   static double rolling_uptime();
  52     //!< give the OS uptime in a more durable form that handles rollovers.
  53
  54   void reset();
  55     //!< sets the stamp time back to now.
  56   void reset(time_representation offset);
  57     //!< sets the stamp forward by "offset" similar to the second constructor.
  58
  59   time_representation value() const { return c_stamp; }
  60     //!< returns the time_stamp in terms of the lower level type.
  61
  62   enum stamp_display_style { STAMP_RELATIVE, STAMP_ABSOLUTE };
  63
  64   basis::astring text_form(stamp_display_style style = STAMP_RELATIVE) const;
  65     //!< returns a simple textual representation of the time_stamp.
  66     /*!< if the "style" is ABSOLUTE, then the stamp is shown in H:M:S.ms
  67     form based on the system uptime.  if the "style" is RELATIVE, then the
  68     stamp is shown as an offset from now. */
  69
  70   static basis::astring notarize(bool add_space = true);
  71     //!< a useful method for getting a textual version of the time "right now".
  72     /*!< this was formerly known as a very useful method called 'utility::timestamp'.
  73     that naming was fairly abusive to keep straight from the time_stamp class, so the
  74     functionality has been absorbed. */
  75
  76   // standard operators: keep in mind that time is represented by an ever
  77   // increasing number.  so, if a value A is less than a value B, that means
  78   // that A is older than B, since it occurred at an earlier time.
  79   virtual bool less_than(const basis::orderable &that) const {
  80     const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
  81     if (!cast) return false;
  82     return c_stamp < cast->c_stamp;
  83   }
  84
  85   virtual bool equal_to(const basis::equalizable &that) const {
  86     const time_stamp *cast = dynamic_cast<const time_stamp *>(&that);
  87     if (!cast) return false;
  88     return c_stamp == cast->c_stamp;
  89   }
  90
  91   // helper functions for using the OS's time support.
  92
  93   static timeval fill_timeval_ms(int milliseconds);
  94     //!< returns a timeval system object that represents the "milliseconds".
  95     /*!< if "milliseconds" is zero, then the returned timeval will
  96     represent zero time passing (rather than infinite duration as some
  97     functions assume). */
  98
  99 private:
 100   time_representation c_stamp;  //!< the low-level time stamp is held here.
 101
 102   void fill_in_time();  //!< stuffs the current time into the held value.
 103
 104   static time_representation get_time_now();
 105     //!< platform specific function that gets uptime.
 106
 107   static rollover_record &rollover_rover();
 108 };
 109
 110 } //namespace.
 111
 112 #endif
 113