include/llvm/Support/TimeValue.h

   1 //===-- TimeValue.h - Declare OS TimeValue Concept --------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This header file declares the operating system TimeValue concept.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_SUPPORT_TIMEVALUE_H
  15 #define LLVM_SUPPORT_TIMEVALUE_H
  16
  17 #include "llvm/Support/DataTypes.h"
  18 #include <string>
  19
  20 namespace llvm {
  21 namespace sys {
  22   /// This class is used where a precise fixed point in time is required. The
  23   /// range of TimeValue spans many hundreds of billions of years both past and
  24   /// present.  The precision of TimeValue is to the nanosecond. However, the
  25   /// actual precision of its values will be determined by the resolution of
  26   /// the system clock. The TimeValue class is used in conjunction with several
  27   /// other lib/System interfaces to specify the time at which a call should
  28   /// timeout, etc.
  29   /// @since 1.4
  30   /// @brief Provides an abstraction for a fixed point in time.
  31   class TimeValue {
  32
  33   /// @name Constants
  34   /// @{
  35   public:
  36
  37     /// A constant TimeValue representing the smallest time
  38     /// value permissible by the class. MinTime is some point
  39     /// in the distant past, about 300 billion years BCE.
  40     /// @brief The smallest possible time value.
  41     static TimeValue MinTime() {
  42       return TimeValue ( INT64_MIN,0 );
  43     }
  44
  45     /// A constant TimeValue representing the largest time
  46     /// value permissible by the class. MaxTime is some point
  47     /// in the distant future, about 300 billion years AD.
  48     /// @brief The largest possible time value.
  49     static TimeValue MaxTime() {
  50       return TimeValue ( INT64_MAX,0 );
  51     }
  52
  53     /// A constant TimeValue representing the base time,
  54     /// or zero time of 00:00:00 (midnight) January 1st, 2000.
  55     /// @brief 00:00:00 Jan 1, 2000 UTC.
  56     static TimeValue ZeroTime() {
  57       return TimeValue ( 0,0 );
  58     }
  59
  60     /// A constant TimeValue for the Posix base time which is
  61     /// 00:00:00 (midnight) January 1st, 1970.
  62     /// @brief 00:00:00 Jan 1, 1970 UTC.
  63     static TimeValue PosixZeroTime() {
  64       return TimeValue ( PosixZeroTimeSeconds,0 );
  65     }
  66
  67     /// A constant TimeValue for the Win32 base time which is
  68     /// 00:00:00 (midnight) January 1st, 1601.
  69     /// @brief 00:00:00 Jan 1, 1601 UTC.
  70     static TimeValue Win32ZeroTime() {
  71       return TimeValue ( Win32ZeroTimeSeconds,0 );
  72     }
  73
  74   /// @}
  75   /// @name Types
  76   /// @{
  77   public:
  78     typedef int64_t SecondsType;    ///< Type used for representing seconds.
  79     typedef int32_t NanoSecondsType;///< Type used for representing nanoseconds.
  80
  81     enum TimeConversions {
  82       NANOSECONDS_PER_SECOND = 1000000000,  ///< One Billion
  83       MICROSECONDS_PER_SECOND = 1000000,    ///< One Million
  84       MILLISECONDS_PER_SECOND = 1000,       ///< One Thousand
  85       NANOSECONDS_PER_MICROSECOND = 1000,   ///< One Thousand
  86       NANOSECONDS_PER_MILLISECOND = 1000000,///< One Million
  87       NANOSECONDS_PER_WIN32_TICK = 100      ///< Win32 tick is 10^7 Hz (10ns)
  88     };
  89
  90   /// @}
  91   /// @name Constructors
  92   /// @{
  93   public:
  94     /// \brief Default construct a time value, initializing to ZeroTime.
  95     TimeValue() : seconds_(0), nanos_(0) {}
  96
  97     /// Caller provides the exact value in seconds and nanoseconds. The
  98     /// \p nanos argument defaults to zero for convenience.
  99     /// @brief Explicit constructor
 100     explicit TimeValue (SecondsType seconds, NanoSecondsType nanos = 0)
 101       : seconds_( seconds ), nanos_( nanos ) { this->normalize(); }
 102
 103     /// Caller provides the exact value as a double in seconds with the
 104     /// fractional part representing nanoseconds.
 105     /// @brief Double Constructor.
 106     explicit TimeValue( double new_time )
 107       : seconds_( 0 ) , nanos_ ( 0 ) {
 108       SecondsType integer_part = static_cast<SecondsType>( new_time );
 109       seconds_ = integer_part;
 110       nanos_ = static_cast<NanoSecondsType>( (new_time -
 111                static_cast<double>(integer_part)) * NANOSECONDS_PER_SECOND );
 112       this->normalize();
 113     }
 114
 115     /// This is a static constructor that returns a TimeValue that represents
 116     /// the current time.
 117     /// @brief Creates a TimeValue with the current time (UTC).
 118     static TimeValue now();
 119
 120   /// @}
 121   /// @name Operators
 122   /// @{
 123   public:
 124     /// Add \p that to \p this.
 125     /// @returns this
 126     /// @brief Incrementing assignment operator.
 127     TimeValue& operator += (const TimeValue& that ) {
 128       this->seconds_ += that.seconds_  ;
 129       this->nanos_ += that.nanos_ ;
 130       this->normalize();
 131       return *this;
 132     }
 133
 134     /// Subtract \p that from \p this.
 135     /// @returns this
 136     /// @brief Decrementing assignment operator.
 137     TimeValue& operator -= (const TimeValue &that ) {
 138       this->seconds_ -= that.seconds_ ;
 139       this->nanos_ -= that.nanos_ ;
 140       this->normalize();
 141       return *this;
 142     }
 143
 144     /// Determine if \p this is less than \p that.
 145     /// @returns True iff *this < that.
 146     /// @brief True if this < that.
 147     int operator < (const TimeValue &that) const { return that > *this; }
 148
 149     /// Determine if \p this is greather than \p that.
 150     /// @returns True iff *this > that.
 151     /// @brief True if this > that.
 152     int operator > (const TimeValue &that) const {
 153       if ( this->seconds_ > that.seconds_ ) {
 154           return 1;
 155       } else if ( this->seconds_ == that.seconds_ ) {
 156           if ( this->nanos_ > that.nanos_ ) return 1;
 157       }
 158       return 0;
 159     }
 160
 161     /// Determine if \p this is less than or equal to \p that.
 162     /// @returns True iff *this <= that.
 163     /// @brief True if this <= that.
 164     int operator <= (const TimeValue &that) const { return that >= *this; }
 165
 166     /// Determine if \p this is greater than or equal to \p that.
 167     /// @returns True iff *this >= that.
 168     int operator >= (const TimeValue &that) const {
 169       if ( this->seconds_ > that.seconds_ ) {
 170           return 1;
 171       } else if ( this->seconds_ == that.seconds_ ) {
 172           if ( this->nanos_ >= that.nanos_ ) return 1;
 173       }
 174       return 0;
 175     }
 176
 177     /// Determines if two TimeValue objects represent the same moment in time.
 178     /// @returns True iff *this == that.
 179     int operator == (const TimeValue &that) const {
 180       return (this->seconds_ == that.seconds_) &&
 181              (this->nanos_ == that.nanos_);
 182     }
 183
 184     /// Determines if two TimeValue objects represent times that are not the
 185     /// same.
 186     /// @returns True iff *this != that.
 187     int operator != (const TimeValue &that) const { return !(*this == that); }
 188
 189     /// Adds two TimeValue objects together.
 190     /// @returns The sum of the two operands as a new TimeValue
 191     /// @brief Addition operator.
 192     friend TimeValue operator + (const TimeValue &tv1, const TimeValue &tv2);
 193
 194     /// Subtracts two TimeValue objects.
 195     /// @returns The difference of the two operands as a new TimeValue
 196     /// @brief Subtraction operator.
 197     friend TimeValue operator - (const TimeValue &tv1, const TimeValue &tv2);
 198
 199   /// @}
 200   /// @name Accessors
 201   /// @{
 202   public:
 203
 204     /// Returns only the seconds component of the TimeValue. The nanoseconds
 205     /// portion is ignored. No rounding is performed.
 206     /// @brief Retrieve the seconds component
 207     SecondsType seconds() const { return seconds_; }
 208
 209     /// Returns only the nanoseconds component of the TimeValue. The seconds
 210     /// portion is ignored.
 211     /// @brief Retrieve the nanoseconds component.
 212     NanoSecondsType nanoseconds() const { return nanos_; }
 213
 214     /// Returns only the fractional portion of the TimeValue rounded down to the
 215     /// nearest microsecond (divide by one thousand).
 216     /// @brief Retrieve the fractional part as microseconds;
 217     uint32_t microseconds() const {
 218       return nanos_ / NANOSECONDS_PER_MICROSECOND;
 219     }
 220
 221     /// Returns only the fractional portion of the TimeValue rounded down to the
 222     /// nearest millisecond (divide by one million).
 223     /// @brief Retrieve the fractional part as milliseconds;
 224     uint32_t milliseconds() const {
 225       return nanos_ / NANOSECONDS_PER_MILLISECOND;
 226     }
 227
 228     /// Returns the TimeValue as a number of microseconds. Note that the value
 229     /// returned can overflow because the range of a uint64_t is smaller than
 230     /// the range of a TimeValue. Nevertheless, this is useful on some operating
 231     /// systems and is therefore provided.
 232     /// @brief Convert to a number of microseconds (can overflow)
 233     uint64_t usec() const {
 234       return seconds_ * MICROSECONDS_PER_SECOND +
 235              ( nanos_ / NANOSECONDS_PER_MICROSECOND );
 236     }
 237
 238     /// Returns the TimeValue as a number of milliseconds. Note that the value
 239     /// returned can overflow because the range of a uint64_t is smaller than
 240     /// the range of a TimeValue. Nevertheless, this is useful on some operating
 241     /// systems and is therefore provided.
 242     /// @brief Convert to a number of milliseconds (can overflow)
 243     uint64_t msec() const {
 244       return seconds_ * MILLISECONDS_PER_SECOND +
 245              ( nanos_ / NANOSECONDS_PER_MILLISECOND );
 246     }
 247
 248     /// Converts the TimeValue into the corresponding number of seconds
 249     /// since the epoch (00:00:00 Jan 1,1970).
 250     uint64_t toEpochTime() const {
 251       return seconds_ - PosixZeroTimeSeconds;
 252     }
 253
 254     /// Converts the TimeValue into the corresponding number of "ticks" for
 255     /// Win32 platforms, correcting for the difference in Win32 zero time.
 256     /// @brief Convert to Win32's FILETIME
 257     /// (100ns intervals since 00:00:00 Jan 1, 1601 UTC)
 258     uint64_t toWin32Time() const {
 259       uint64_t result = (uint64_t)10000000 * (seconds_ - Win32ZeroTimeSeconds);
 260       result += nanos_ / NANOSECONDS_PER_WIN32_TICK;
 261       return result;
 262     }
 263
 264     /// Provides the seconds and nanoseconds as results in its arguments after
 265     /// correction for the Posix zero time.
 266     /// @brief Convert to timespec time (ala POSIX.1b)
 267     void getTimespecTime( uint64_t& seconds, uint32_t& nanos ) const {
 268       seconds = seconds_ - PosixZeroTimeSeconds;
 269       nanos = nanos_;
 270     }
 271
 272     /// Provides conversion of the TimeValue into a readable time & date.
 273     /// @returns std::string containing the readable time value
 274     /// @brief Convert time to a string.
 275     std::string str() const;
 276
 277   /// @}
 278   /// @name Mutators
 279   /// @{
 280   public:
 281     /// The seconds component of the TimeValue is set to \p sec without
 282     /// modifying the nanoseconds part.  This is useful for whole second
 283     /// arithmetic.
 284     /// @brief Set the seconds component.
 285     void seconds (SecondsType sec ) {
 286       this->seconds_ = sec;
 287       this->normalize();
 288     }
 289
 290     /// The nanoseconds component of the TimeValue is set to \p nanos without
 291     /// modifying the seconds part. This is useful for basic computations
 292     /// involving just the nanoseconds portion. Note that the TimeValue will be
 293     /// normalized after this call so that the fractional (nanoseconds) portion
 294     /// will have the smallest equivalent value.
 295     /// @brief Set the nanoseconds component using a number of nanoseconds.
 296     void nanoseconds ( NanoSecondsType nanos ) {
 297       this->nanos_ = nanos;
 298       this->normalize();
 299     }
 300
 301     /// The seconds component remains unchanged.
 302     /// @brief Set the nanoseconds component using a number of microseconds.
 303     void microseconds ( int32_t micros ) {
 304       this->nanos_ = micros * NANOSECONDS_PER_MICROSECOND;
 305       this->normalize();
 306     }
 307
 308     /// The seconds component remains unchanged.
 309     /// @brief Set the nanoseconds component using a number of milliseconds.
 310     void milliseconds ( int32_t millis ) {
 311       this->nanos_ = millis * NANOSECONDS_PER_MILLISECOND;
 312       this->normalize();
 313     }
 314
 315     /// @brief Converts from microsecond format to TimeValue format
 316     void usec( int64_t microseconds ) {
 317       this->seconds_ = microseconds / MICROSECONDS_PER_SECOND;
 318       this->nanos_ = NanoSecondsType(microseconds % MICROSECONDS_PER_SECOND) *
 319         NANOSECONDS_PER_MICROSECOND;
 320       this->normalize();
 321     }
 322
 323     /// @brief Converts from millisecond format to TimeValue format
 324     void msec( int64_t milliseconds ) {
 325       this->seconds_ = milliseconds / MILLISECONDS_PER_SECOND;
 326       this->nanos_ = NanoSecondsType(milliseconds % MILLISECONDS_PER_SECOND) *
 327         NANOSECONDS_PER_MILLISECOND;
 328       this->normalize();
 329     }
 330
 331     /// Converts the \p seconds argument from PosixTime to the corresponding
 332     /// TimeValue and assigns that value to \p this.
 333     /// @brief Convert seconds form PosixTime to TimeValue
 334     void fromEpochTime( SecondsType seconds ) {
 335       seconds_ = seconds + PosixZeroTimeSeconds;
 336       nanos_ = 0;
 337       this->normalize();
 338     }
 339
 340     /// Converts the \p win32Time argument from Windows FILETIME to the
 341     /// corresponding TimeValue and assigns that value to \p this.
 342     /// @brief Convert seconds form Windows FILETIME to TimeValue
 343     void fromWin32Time( uint64_t win32Time ) {
 344       this->seconds_ = win32Time / 10000000 + Win32ZeroTimeSeconds;
 345       this->nanos_ = NanoSecondsType(win32Time  % 10000000) * 100;
 346     }
 347
 348   /// @}
 349   /// @name Implementation
 350   /// @{
 351   private:
 352     /// This causes the values to be represented so that the fractional
 353     /// part is minimized, possibly incrementing the seconds part.
 354     /// @brief Normalize to canonical form.
 355     void normalize();
 356
 357   /// @}
 358   /// @name Data
 359   /// @{
 360   private:
 361     /// Store the values as a <timeval>.
 362     SecondsType      seconds_;///< Stores the seconds part of the TimeVal
 363     NanoSecondsType  nanos_;  ///< Stores the nanoseconds part of the TimeVal
 364
 365     static const SecondsType PosixZeroTimeSeconds;
 366     static const SecondsType Win32ZeroTimeSeconds;
 367   /// @}
 368
 369   };
 370
 371 inline TimeValue operator + (const TimeValue &tv1, const TimeValue &tv2) {
 372   TimeValue sum (tv1.seconds_ + tv2.seconds_, tv1.nanos_ + tv2.nanos_);
 373   sum.normalize ();
 374   return sum;
 375 }
 376
 377 inline TimeValue operator - (const TimeValue &tv1, const TimeValue &tv2) {
 378   TimeValue difference (tv1.seconds_ - tv2.seconds_, tv1.nanos_ - tv2.nanos_ );
 379   difference.normalize ();
 380   return difference;
 381 }
 382
 383 } // namespace sys
 384 } // namespace llvm
 385
 386 #endif