LLVM API Documentation

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TimeValue.h
Go to the documentation of this file.
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 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 
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
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.
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.
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 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) *
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) *
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
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 }
384 }
385 
386 #endif
std::string str() const
Convert time to a string.
TimeValue()
Default construct a time value, initializing to ZeroTime.
Definition: TimeValue.h:86
static TimeValue now()
Creates a TimeValue with the current time (UTC).
TimeValue(SecondsType seconds, NanoSecondsType nanos=0)
Explicit constructor.
Definition: TimeValue.h:91
void microseconds(int32_t micros)
Set the nanoseconds component using a number of microseconds.
Definition: TimeValue.h:303
static const TimeValue ZeroTime
00:00:00 Jan 1, 2000 UTC.
Definition: TimeValue.h:52
void seconds(SecondsType sec)
Set the seconds component.
Definition: TimeValue.h:285
int32_t NanoSecondsType
Type used for representing nanoseconds.
Definition: TimeValue.h:69
TimeValue operator-(const TimeValue &tv1, const TimeValue &tv2)
Definition: TimeValue.h:377
static const TimeValue MinTime
The smallest possible time value.
Definition: TimeValue.h:41
SecondsType seconds() const
Retrieve the seconds component.
Definition: TimeValue.h:198
uint64_t usec() const
Convert to a number of microseconds (can overflow)
Definition: TimeValue.h:224
NanoSecondsType nanoseconds() const
Retrieve the nanoseconds component.
Definition: TimeValue.h:203
void msec(int64_t milliseconds)
Converts from millisecond format to TimeValue format.
Definition: TimeValue.h:324
void milliseconds(int32_t millis)
Set the nanoseconds component using a number of milliseconds.
Definition: TimeValue.h:310
int operator<=(const TimeValue &that) const
True if this <= that.
Definition: TimeValue.h:155
TimeValue(double new_time)
Double Constructor.
Definition: TimeValue.h:97
static const TimeValue MaxTime
The largest possible time value.
Definition: TimeValue.h:47
TimeValue & operator+=(const TimeValue &that)
Incrementing assignment operator.
Definition: TimeValue.h:118
uint64_t toEpochTime() const
Definition: TimeValue.h:250
int operator<(const TimeValue &that) const
True if this < that.
Definition: TimeValue.h:138
uint64_t msec() const
Convert to a number of milliseconds (can overflow)
Definition: TimeValue.h:234
void fromWin32Time(uint64_t win32Time)
Convert seconds form Windows FILETIME to TimeValue.
Definition: TimeValue.h:343
int operator==(const TimeValue &that) const
Definition: TimeValue.h:170
int operator!=(const TimeValue &that) const
Definition: TimeValue.h:178
TimeValue operator+(const TimeValue &tv1, const TimeValue &tv2)
Definition: TimeValue.h:371
int64_t SecondsType
Type used for representing seconds.
Definition: TimeValue.h:68
int operator>=(const TimeValue &that) const
Definition: TimeValue.h:159
static const TimeValue Win32ZeroTime
00:00:00 Jan 1, 1601 UTC.
Definition: TimeValue.h:62
static const TimeValue PosixZeroTime
00:00:00 Jan 1, 1970 UTC.
Definition: TimeValue.h:57
uint32_t milliseconds() const
Retrieve the fractional part as milliseconds;.
Definition: TimeValue.h:215
uint64_t toPosixTime() const
Convert to unix time (100 nanoseconds since 12:00:00a Jan 1,1970)
Definition: TimeValue.h:242
void fromEpochTime(SecondsType seconds)
Convert seconds form PosixTime to TimeValue.
Definition: TimeValue.h:334
void usec(int64_t microseconds)
Converts from microsecond format to TimeValue format.
Definition: TimeValue.h:316
int operator>(const TimeValue &that) const
True if this > that.
Definition: TimeValue.h:143
friend TimeValue operator+(const TimeValue &tv1, const TimeValue &tv2)
Addition operator.
Definition: TimeValue.h:371
void getTimespecTime(uint64_t &seconds, uint32_t &nanos) const
Convert to timespec time (ala POSIX.1b)
Definition: TimeValue.h:267
Provides an abstraction for a fixed point in time.
Definition: TimeValue.h:31
uint32_t microseconds() const
Retrieve the fractional part as microseconds;.
Definition: TimeValue.h:208
friend TimeValue operator-(const TimeValue &tv1, const TimeValue &tv2)
Subtraction operator.
Definition: TimeValue.h:377
TimeValue & operator-=(const TimeValue &that)
Decrementing assignment operator.
Definition: TimeValue.h:128
uint64_t toWin32Time() const
Convert to Win32's FILETIME (100ns intervals since 00:00:00 Jan 1, 1601 UTC)
Definition: TimeValue.h:258
void nanoseconds(NanoSecondsType nanos)
Set the nanoseconds component using a number of nanoseconds.
Definition: TimeValue.h:296