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