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