ACE/ace/Time_Value.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Time_Value.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_TIME_VALUE_H
  12 #define ACE_TIME_VALUE_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/os_include/os_time.h"
  23 #include "ace/Truncate.h"
  24 #include <chrono>
  25 #include <ostream>
  26
  27 // Define some helpful constants.
  28 // Not type-safe, and signed.  For backward compatibility.
  29 #define ACE_ONE_SECOND_IN_MSECS 1000L
  30 suseconds_t const ACE_ONE_SECOND_IN_USECS = 1000000;
  31 #define ACE_ONE_SECOND_IN_NSECS 1000000000L
  32
  33 // needed for ACE_UINT64
  34 #include "ace/Basic_Types.h"
  35
  36 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  37
  38 /**
  39  * @class ACE_Time_Value
  40  *
  41  * @brief Operations on "timeval" structures, which express time in
  42  * seconds (secs) and microseconds (usecs).
  43  *
  44  * This class centralizes all the time related processing in
  45  * ACE.  These time values are typically used in conjunction with OS
  46  * mechanisms like <select>, <poll>, or <cond_timedwait>.
  47  */
  48 class ACE_Export ACE_Time_Value
  49 {
  50 public:
  51   /// Constant "0".
  52   static const ACE_Time_Value zero;
  53
  54   /**
  55    * Constant for maximum time representable.  Note that this time is
  56    * not intended for use with <select> or other calls that may have
  57    * *their own* implementation-specific maximum time representations.
  58    * Its primary use is in time computations such as those used by the
  59    * dynamic subpriority strategies in the ACE_Dynamic_Message_Queue
  60    * class.
  61    */
  62   static const ACE_Time_Value max_time;
  63
  64   /// Default Constructor.
  65   ACE_Time_Value ();
  66
  67   /// Constructor.
  68   explicit ACE_Time_Value (time_t sec, suseconds_t usec = 0);
  69
  70   // = Methods for converting to/from various time formats.
  71
  72   /// Construct the ACE_Time_Value from a timeval.
  73   explicit ACE_Time_Value (const struct timeval &t);
  74
  75   /// Construct the ACE_Time_Value object from a timespec_t.
  76   explicit ACE_Time_Value (const timespec_t &t);
  77
  78   ACE_Time_Value (const ACE_Time_Value&) = default;
  79   ACE_Time_Value (ACE_Time_Value&&) = default;
  80
  81   /// Construct the ACE_Time_Value object from a chrono duration.
  82   template< class Rep, class Period >
  83   explicit ACE_Time_Value (const std::chrono::duration<Rep, Period>& duration)
  84   {
  85     this->set (duration);
  86   }
  87
  88   /// Destructor
  89   virtual ~ACE_Time_Value () = default;
  90
  91   /// Declare the dynamic allocation hooks.
  92   ACE_ALLOC_HOOK_DECLARE;
  93
  94 # if defined (ACE_WIN32)
  95   /// Construct the ACE_Time_Value object from a Win32 FILETIME
  96   explicit ACE_Time_Value (const FILETIME &ft);
  97 # endif /* ACE_WIN32 */
  98
  99   /// Initializes the ACE_Time_Value from seconds and useconds.
 100   void set (time_t sec, suseconds_t usec);
 101
 102   /// Initializes the ACE_Time_Value from a double, which is assumed to be
 103   /// in second format, with any remainder treated as microseconds.
 104   void set (double d);
 105
 106   /// Initializes the ACE_Time_Value from a timeval.
 107   void set (const timeval &t);
 108
 109   /// Initializes the ACE_Time_Value object from a timespec_t.
 110   void set (const timespec_t &t);
 111
 112 # if defined (ACE_WIN32)
 113   /// Initializes the ACE_Time_Value object from a Win32 FILETIME.
 114   void set (const FILETIME &ft);
 115 # endif /* ACE_WIN32 */
 116
 117   /// Initializes the ACE_Time_Value object from a std::duration.
 118   template< class Rep, class Period >
 119   void set (const std::chrono::duration<Rep, Period>& duration)
 120   {
 121     std::chrono::seconds const s {
 122       std::chrono::duration_cast<std::chrono::seconds> (duration)};
 123
 124     std::chrono::microseconds const usec {
 125       std::chrono::duration_cast<std::chrono::microseconds>(
 126         duration % std::chrono::seconds (1))};
 127     this->set (ACE_Utils::truncate_cast<time_t>(s.count ()), ACE_Utils::truncate_cast<suseconds_t>(usec.count ()));
 128   }
 129
 130   /// Converts from ACE_Time_Value format into milliseconds format.
 131   /**
 132    * @return Sum of second field (in milliseconds) and microsecond field
 133    *         (in milliseconds).  Note that this method can overflow if
 134    *         the second and microsecond field values are large, so use
 135    *         the msec (ACE_UINT64 &ms) method instead.
 136    *
 137    * @note The semantics of this method differs from the sec() and
 138    *       usec() methods.  There is no analogous "millisecond"
 139    *       component in an ACE_Time_Value.
 140    */
 141   unsigned long msec () const;
 142
 143   /// Converts from ACE_Time_Value format into milliseconds format.
 144   /**
 145    * @return Sum of second field (in milliseconds) and microsecond field
 146    *         (in milliseconds).
 147    *
 148    * @note The semantics of this method differs from the sec() and
 149    *       usec() methods.  There is no analogous "millisecond"
 150    *       component in an ACE_Time_Value.
 151    */
 152   ACE_UINT64 get_msec () const;
 153
 154   /// Converts from ACE_Time_Value format into milliseconds format.
 155   /**
 156    * @return Sum of second field (in milliseconds) and microsecond field
 157    *         (in milliseconds) and return them via the @param ms parameter.
 158    *
 159    * @note The semantics of this method differs from the sec() and
 160    *       usec() methods.  There is no analogous "millisecond"
 161    *       component in an ACE_Time_Value.
 162    *
 163    * @deprecated Use get_msec() instead.
 164    */
 165   void msec (ACE_UINT64 &ms) const;
 166
 167   /// Converts from ACE_Time_Value format into milliseconds format.
 168   /**
 169    * @return Sum of second field (in milliseconds) and microsecond field
 170    *         (in milliseconds) and return them via the @param ms parameter.
 171    *
 172    * @note The semantics of this method differs from the sec() and
 173    *       usec() methods.  There is no analogous "millisecond"
 174    *       component in an ACE_Time_Value.
 175    *
 176    * @deprecated Use get_msec() instead.
 177    */
 178   void msec (ACE_UINT64 &ms) /* const */;
 179
 180   /// Converts from milli-seconds format into ACE_Time_Value format.
 181   /**
 182    * @note The semantics of this method differs from the sec() and
 183    *       usec() methods.  There is no analogous "millisecond"
 184    *       component in an ACE_Time_Value.
 185    */
 186   void set_msec (const ACE_UINT64 &ms);
 187
 188   /// Converts from milli-seconds format into ACE_Time_Value format.
 189   /**
 190    * @note The semantics of this method differs from the sec() and
 191    *       usec() methods.  There is no analogous "millisecond"
 192    *       component in an ACE_Time_Value.
 193    */
 194   void msec (long);
 195
 196   /// Converts from milli-seconds format into ACE_Time_Value format.
 197   /**
 198    * @note The semantics of this method differs from the sec() and
 199    *       usec() methods.  There is no analogous "millisecond"
 200    *       component in an ACE_Time_Value.
 201    */
 202   void msec (int);  // converted to long then calls above.
 203
 204   /// Returns the value of the object as a timespec_t.
 205   operator timespec_t () const;
 206
 207   /// Returns the value of the object as a timeval.
 208   operator timeval () const;
 209
 210   /// Returns a pointer to the object as a timeval.
 211   operator const timeval *() const;
 212
 213 # if defined (ACE_WIN32)
 214   /// Returns the value of the object as a Win32 FILETIME.
 215   operator FILETIME () const;
 216 # endif /* ACE_WIN32 */
 217
 218   // = The following are accessor/mutator methods.
 219
 220   /// Get seconds.
 221   /**
 222    * @return The second field/component of this ACE_Time_Value.
 223    *
 224    * @note The semantics of this method differs from the msec()
 225    *       method.
 226    */
 227   time_t sec () const;
 228
 229   /// Set seconds.
 230   void sec (time_t sec);
 231
 232   /// Get microseconds.
 233   /**
 234    * @return The microsecond field/component of this ACE_Time_Value.
 235    *
 236    * @note The semantics of this method differs from the msec()
 237    *       method.
 238    */
 239   suseconds_t usec () const;
 240
 241   /// Set microseconds.
 242   void usec (suseconds_t usec);
 243
 244   /**
 245    * @return Sum of second field (in microseconds) and microsecond field
 246    *         and return them via the @param usec parameter.
 247    */
 248   void to_usec (ACE_UINT64 &usec) const;
 249
 250   // = The following arithmetic methods operate on ACE_Time_Value's.
 251
 252   /// Add @a tv to this.
 253   ACE_Time_Value &operator += (const ACE_Time_Value &tv);
 254
 255   /// Add @a tv to this.
 256   ACE_Time_Value &operator += (time_t tv);
 257
 258   /// Assign @a tv to this
 259   ACE_Time_Value &operator = (const ACE_Time_Value &) = default;
 260   ACE_Time_Value &operator = (ACE_Time_Value &&)  = default;
 261
 262   /// Assign @a tv to this
 263   ACE_Time_Value &operator = (time_t tv);
 264
 265   /// Subtract @a tv to this.
 266   ACE_Time_Value &operator -= (const ACE_Time_Value &tv);
 267
 268   /// Subtract @a tv to this.
 269   ACE_Time_Value &operator -= (time_t tv);
 270
 271   /// Add @a std::duration to this.
 272   template< class Rep, class Period >
 273   ACE_Time_Value &operator += (const std::chrono::duration<Rep, Period>& duration)
 274   {
 275     const ACE_Time_Value tv (duration);
 276     this->sec (this->sec () + tv.sec ());
 277     this->usec (this->usec () + tv.usec ());
 278     this->normalize ();
 279     return *this;
 280   }
 281
 282   /// Assign @a std::duration to this
 283   template< class Rep, class Period >
 284   ACE_Time_Value &operator = (const std::chrono::duration<Rep, Period>& duration)
 285   {
 286     this->set (duration);
 287     return *this;
 288   }
 289
 290   /// Subtract @a std::duration to this.
 291   template< class Rep, class Period >
 292   ACE_Time_Value &operator -= (const std::chrono::duration<Rep, Period>& duration)
 293   {
 294     const ACE_Time_Value tv (duration);
 295     this->sec (this->sec () - tv.sec ());
 296     this->usec (this->usec () - tv.usec ());
 297     this->normalize ();
 298     return *this;
 299   }
 300
 301   /**
 302     \brief Multiply the time value by the @a d factor.
 303     \note The result of the operator is valid for results from range
 304     < (ACE_INT32_MIN, -999999), (ACE_INT32_MAX, 999999) >. Result
 305     outside this range are saturated to a limit.
 306      */
 307   ACE_Time_Value &operator *= (double d);
 308
 309   /// Increment microseconds as postfix.
 310   /**
 311    * @note The only reason this is here is to allow the use of ACE_Atomic_Op
 312    * with ACE_Time_Value.
 313    */
 314   ACE_Time_Value operator++ (int);
 315
 316   /// Increment microseconds as prefix.
 317   /**
 318    * @note The only reason this is here is to allow the use of ACE_Atomic_Op
 319    * with ACE_Time_Value.
 320    */
 321   ACE_Time_Value &operator++ ();
 322
 323   /// Decrement microseconds as postfix.
 324   /**
 325    * @note The only reason this is here is to allow the use of ACE_Atomic_Op
 326    * with ACE_Time_Value.
 327    */
 328   ACE_Time_Value operator-- (int);
 329
 330   /// Decrement microseconds as prefix.
 331   /**
 332    * @note The only reason this is here is to allow the use of ACE_Atomic_Op
 333    * with ACE_Time_Value.
 334    */
 335   ACE_Time_Value &operator-- ();
 336
 337   /// Adds two ACE_Time_Value objects together, returns the sum.
 338   friend ACE_Export ACE_Time_Value operator + (const ACE_Time_Value &tv1,
 339                                                const ACE_Time_Value &tv2);
 340
 341   /// Subtracts two ACE_Time_Value objects, returns the difference.
 342   friend ACE_Export ACE_Time_Value operator - (const ACE_Time_Value &tv1,
 343                                                const ACE_Time_Value &tv2);
 344
 345   /// True if @a tv1 < @a tv2.
 346   friend ACE_Export bool operator < (const ACE_Time_Value &tv1,
 347                                      const ACE_Time_Value &tv2);
 348
 349   /// True if @a tv1 > @a tv2.
 350   friend ACE_Export bool operator > (const ACE_Time_Value &tv1,
 351                                      const ACE_Time_Value &tv2);
 352
 353   /// True if @a tv1 <= @a tv2.
 354   friend ACE_Export bool operator <= (const ACE_Time_Value &tv1,
 355                                       const ACE_Time_Value &tv2);
 356
 357   /// True if @a tv1 >= @a tv2.
 358   friend ACE_Export bool operator >= (const ACE_Time_Value &tv1,
 359                                       const ACE_Time_Value &tv2);
 360
 361   /// True if @a tv1 == @a tv2.
 362   friend ACE_Export bool operator == (const ACE_Time_Value &tv1,
 363                                       const ACE_Time_Value &tv2);
 364
 365   /// True if @a tv1 != @a tv2.
 366   friend ACE_Export bool operator != (const ACE_Time_Value &tv1,
 367                                       const ACE_Time_Value &tv2);
 368
 369   //@{
 370   /// Multiplies the time value by @a d
 371   friend ACE_Export ACE_Time_Value operator * (double d,
 372                                                const ACE_Time_Value &tv);
 373
 374   friend ACE_Export ACE_Time_Value operator * (const ACE_Time_Value &tv,
 375                                                double d);
 376   //@}
 377
 378   /// Get current time of day.
 379   /**
 380    * @return  Time value representing current time of day.
 381    *
 382    * @note    This method is overloaded in the time policy based template
 383    *          instantiations derived from this class. Allows for time policy
 384    *          aware time values.
 385    */
 386   virtual ACE_Time_Value now () const;
 387
 388   /// Converts absolute time value to time value relative to current time of day.
 389   /**
 390    * @return  Relative time value.
 391    *
 392    * @note    This method is overloaded in the time policy based template
 393    *          instantiations derived from this class. Allows for time policy
 394    *          aware time values.
 395    *          The developer is responsible for making sure this is an absolute
 396    *          time value compatible with the active time policy (which is system
 397    *          time for the base class).
 398    */
 399   virtual ACE_Time_Value to_relative_time () const;
 400
 401   /// Converts relative time value to absolute time value based on current time of day.
 402   /**
 403    * @return  Absolute time value.
 404    *
 405    * @note    This method is overloaded in the time policy based template
 406    *          instantiations derived from this class. Allows for time policy
 407    *          aware time values.
 408    *          The developer is responsible for making sure this is a relative
 409    *          time value. Current time of day is determined based on time policy
 410    *          (which is system time for the base class).
 411    */
 412   virtual ACE_Time_Value to_absolute_time () const;
 413
 414   /// Duplicates this time value (incl. time policy).
 415   /**
 416    * @return  Dynamically allocated time value copy.
 417    *
 418    * @note    The caller is responsible for freeing the copy when it's not needed
 419    *          anymore.
 420    */
 421   virtual ACE_Time_Value * duplicate () const;
 422
 423   /// Dump is a no-op.
 424   /**
 425    * The dump() method is a no-op.  It's here for backwards compatibility
 426    * only, but does not dump anything. Invoking logging methods here
 427    * violates layering restrictions in ACE because this class is part
 428    * of the OS layer and @c ACE_Log_Msg is at a higher level.
 429    */
 430   void dump () const;
 431
 432 # if defined (ACE_WIN32)
 433   /// Const time difference between FILETIME and POSIX time.
 434   static const DWORDLONG FILETIME_to_timval_skew;
 435 # endif /* ACE_WIN32 */
 436
 437 private:
 438   /// Put the timevalue into a canonical form.
 439   void normalize (bool saturate = false);
 440
 441   /// Store the values as a timeval.
 442 #if defined (ACE_HAS_TIME_T_LONG_MISMATCH)
 443   // Windows' timeval is non-conformant, so swap in a struct that conforms
 444   // to the proper data types to represent the entire time range that this
 445   // class's API can accept.
 446   // Also, since this class can supply a pointer to a timeval that things
 447   // like select() expect, we need the OS-defined one as well. To make this
 448   // available, use a real timeval called ext_tv_ and set it up when needed.
 449   // Since this is most often for relative times that don't approach 32 bits
 450   // in size, reducing a time_t to fit should be no problem.
 451   struct {
 452     time_t tv_sec;
 453     suseconds_t tv_usec;
 454   } tv_;
 455   timeval ext_tv_;
 456 #else
 457   timeval tv_;
 458 #endif /* ACE_HAS_TIME_T_LONG_MISMATCH */
 459 };
 460
 461 extern ACE_Export std::ostream &operator<<(std::ostream &o, const ACE_Time_Value &v );
 462
 463 ACE_END_VERSIONED_NAMESPACE_DECL
 464
 465 // Additional chrono operators.
 466 namespace std
 467 {
 468   namespace chrono
 469   {
 470     /**
 471     * @name Streaming ACE_Time_Value to chrono
 472     *
 473     * Streaming an ACE_Time_Value into one of the chrono types (nanoseconds,
 474     * microseconds, milliseconds, seconds, minutes, or hours).
 475     *
 476     */
 477     //@{
 478     ACE_Export nanoseconds& operator <<(nanoseconds &ns, ACE_Time_Value const &tv);
 479     ACE_Export microseconds& operator <<(microseconds &us, ACE_Time_Value const &tv);
 480     ACE_Export milliseconds& operator <<(milliseconds &ms, ACE_Time_Value const &tv);
 481     ACE_Export seconds& operator <<(seconds &s, ACE_Time_Value const &tv);
 482     ACE_Export minutes& operator <<(minutes &m, ACE_Time_Value const &tv);
 483     ACE_Export hours& operator <<(hours &h, ACE_Time_Value const &tv);
 484     //@}
 485
 486     /**
 487     * @name Adding ACE_Time_Value to chrono
 488     *
 489     * Adding an ACE_Time_Value to one of the chrono types (nanoseconds,
 490     * microseconds, milliseconds, seconds, minutes, or hours).
 491     *
 492     */
 493     //@{
 494     ACE_Export nanoseconds& operator +=(nanoseconds &ns, ACE_Time_Value const &tv);
 495     ACE_Export microseconds& operator +=(microseconds &us, ACE_Time_Value const &tv);
 496     ACE_Export milliseconds& operator +=(milliseconds &ms, ACE_Time_Value const &tv);
 497     ACE_Export seconds& operator +=(seconds &s, ACE_Time_Value const &tv);
 498     ACE_Export minutes& operator +=(minutes &m, ACE_Time_Value const &tv);
 499     ACE_Export hours& operator +=(hours &h, ACE_Time_Value const &tv);
 500     //@}
 501
 502     /**
 503     * @name Substracting ACE_Time_Value from chrono
 504     *
 505     * Substracting an ACE_Time_Value from one of the chrono types (nanoseconds,
 506     * microseconds, milliseconds, seconds, minutes, or hours).
 507     *
 508     */
 509     //@{
 510     ACE_Export nanoseconds& operator -=(nanoseconds &ns, ACE_Time_Value const &tv);
 511     ACE_Export microseconds& operator -=(microseconds &us, ACE_Time_Value const &tv);
 512     ACE_Export milliseconds& operator -=(milliseconds &ms, ACE_Time_Value const &tv);
 513     ACE_Export seconds& operator -=(seconds &s, ACE_Time_Value const &tv);
 514     ACE_Export minutes& operator -=(minutes &m, ACE_Time_Value const &tv);
 515     ACE_Export hours& operator -=(hours &h, ACE_Time_Value const &tv);
 516     //@}
 517   }
 518 }
 519
 520 #if defined (__ACE_INLINE__)
 521 #include "ace/Time_Value.inl"
 522 #endif /* __ACE_INLINE__ */
 523
 524 #if defined (__MINGW32__)
 525 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 526 // The MingW linker has problems with the exported statics
 527 // zero and max_time with these two statics the linker will be able to
 528 // resolve the static exported symbols.
 529 static const ACE_Time_Value& __zero_time = ACE_Time_Value::zero;
 530 static const ACE_Time_Value& __max_time = ACE_Time_Value::max_time;
 531 ACE_END_VERSIONED_NAMESPACE_DECL
 532 #endif /* __MINGW32__ */
 533
 534 #include /**/ "ace/post.h"
 535
 536 #endif /* ACE_TIME_VALUE_H */