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 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
371inline 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
377inline 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}
384}
385
386#endif
387