Scheduler/ClockService.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
   5 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief ClockService public header */
  25
  26 #ifndef HH_ClockService_
  27 #define HH_ClockService_ 1
  28
  29 // Custom includes
  30 #include <boost/utility.hpp>
  31 #include <boost/date_time/posix_time/posix_time_types.hpp>
  32
  33 //#include "ClockService.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37
  38     // Implementation note:
  39     //
  40     // The clock value is represented as a 64bit unsigned integer number of nanosecods elapsed since
  41     // the construction of the ClockService object.
  42     //
  43     // The implementation must provide two features:
  44     // a) It must reliably detect clock changes
  45     // b) In case of a clock change a reasonably accurate fallback clock value must be provided
  46     //
  47     // We do this using setitimer/getitimer. We setup an interval timer sending SIGALRM whenever
  48     // CheckInverval seconds have elapsed.
  49     //
  50     // On every SIGALRM signal we save the current value of gettimeofday(). If this new value is
  51     // substantially different from the currently saved value + CheckInterval, the clock has been
  52     // changed.
  53     //
  54     // Whenever the current clock value is requested using now(), the current gettimeofday() value
  55     // is compared with the saved value. If the difference is substantially more than CheckInterval,
  56     // the clock has been changed.
  57     //
  58     // This provides clock skew detection. If clock skew is detected, we need to move base_ by the
  59     // amount the time has been changed. To do this we need an as accurate as possible approximation
  60     // of the expected current time value. We need to differentiate two cases:
  61     //
  62     // a) Clock skew detected in within now()
  63     //
  64     // In this case, we use getitimer() to find the time remaining in the timer. Using this value and
  65     // an the saved gettimeofday() value we can adjust base_ accordingly.
  66     //
  67     // b) Clock skew detected in the signal handler
  68     //
  69     // In this case we use the save gettimeofday() value + CheckInterval to adjust base_.
  70
  71     /** \brief Reliable high precision monotonous clock source
  72
  73         The ClockService provides a highly accurate monotonous clock source based on
  74         gettimeofday(). However, it takes additional precautions to detect clock skew.
  75
  76         \fixme Implement the clock-skew detection
  77       */
  78     class ClockService
  79         : boost::noncopyable
  80     {
  81     public:
  82         ///////////////////////////////////////////////////////////////////////////
  83         // Types
  84
  85         /** \brief ClockService timer data type
  86
  87             Unsigned integer type representing scheduler time. Scheduler time is measured in
  88             nanoseconds relative to some implementation defined reference time.
  89          */
  90         typedef boost::uint_fast64_t clock_type;
  91
  92         /** \brief Absolute time data type
  93
  94             Boost.DateTime datatype used to represent absolute date/time values.
  95          */
  96         typedef boost::posix_time::ptime abstime_type;
  97
  98         static unsigned const CheckInterval = 1;
  99
 100         ///////////////////////////////////////////////////////////////////////////
 101         ///\name Structors and default members
 102         ///@{
 103
 104         ~ClockService();
 105
 106         ///@}
 107         ///////////////////////////////////////////////////////////////////////////
 108
 109         static clock_type now();  ///< Return current clock value
 110
 111         static abstime_type abstime(clock_type clock); ///< Convert clock to absolute time
 112                                         /**< This member converts a clock value into an absolute
 113                                              Boost.DateTime value.
 114                                              \note You should not base timeout calculations on this
 115                                                  absolute time value. Clock time is guaranteed to be
 116                                                  monotonous, absolute time may be non-monotonous if
 117                                                  the system date/time is changed. */
 118
 119         static clock_type clock(abstime_type time); ///< Convert absolute time to clock value
 120                                         /**< This member converst an absolute time value into the
 121                                              corresponding clock value.
 122                                              \see abstime */
 123
 124     protected:
 125
 126     private:
 127         ClockService();
 128
 129         static ClockService & instance();
 130
 131         boost::posix_time::ptime base_;
 132     };
 133
 134
 135 }
 136
 137 ///////////////////////////////hh.e////////////////////////////////////////
 138 #include "ClockService.cci"
 139 //#include "ClockService.ct"
 140 //#include "ClockService.cti"
 141 #endif
 142
 143 \f
 144 // Local Variables:
 145 // mode: c++
 146 // fill-column: 100
 147 // comment-column: 40
 148 // c-file-style: "senf"
 149 // indent-tabs-mode: nil
 150 // ispell-local-dictionary: "american"
 151 // compile-command: "scons -u test"
 152 // End: