4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
24 \brief ClockService public header */
26 #ifndef HH_SENF_Scheduler_ClockService_
27 #define HH_SENF_Scheduler_ClockService_ 1
31 #include <boost/utility.hpp>
32 #include <boost/date_time/posix_time/posix_time.hpp>
33 #include <boost/scoped_ptr.hpp>
34 #include <boost/cstdint.hpp>
35 #include <senf/config.hh>
36 #include <senf/Utils/singleton.hh>
37 #include <senf/Utils/Console/Parse.hh>
39 //#include "ClockService.mpp"
40 ///////////////////////////////hh.p////////////////////////////////////////
45 namespace detail { class ClockServiceTest; }
48 // Implementation note: The clock value is represented as a 64bit unsigned integer number of
49 // nanoseconds based on the CLOCK_MONOTONIC POSIX clock.
51 // To allow conversion between clock value and absolute time, the ClockService samples the
52 // absolute current time and the clock value when the conversion is performed. This is done at
53 // most once per second on a if-needed basis.
55 /** \brief Reliable high precision monotonous clock source
57 The ClockService provides a highly accurate monotonous clock source based on
58 gettimeofday(). However, it takes additional precautions to detect clock skew.
60 \implementation The funny mixture of static and non-static members stems from the old
61 implementation based on interval timers and gettimeofday(). The current implementation
62 uses POSIX clocks and is much simpler and more precise.
65 : singleton<ClockService>
68 ///////////////////////////////////////////////////////////////////////////
71 /** \brief ClockService timer data type
73 Unsigned integer type representing scheduler time. Scheduler time is measured in
74 nanoseconds relative to some implementation defined reference time.
76 typedef config::time_type clock_type;
78 /** \brief Supplementary integer type
80 This type is used to represent varies supplementary values (e.g. number of microseconds)
82 typedef boost::int_fast64_t int64_type;
84 /** \brief Absolute time data type
86 Boost.DateTime datatype used to represent absolute date/time values.
88 typedef boost::posix_time::ptime abstime_type;
90 /** \brief Relative time data type
92 Boost.DateTime datatype used to represent time intervals
94 typedef boost::posix_time::time_duration reltime_type;
96 ///////////////////////////////////////////////////////////////////////////
98 static clock_type now(); ///< Return current clock value
100 static abstime_type abstime(clock_type clock); ///< Convert clock to absolute time
101 /**< This member converts a clock value into an absolute
102 Boost.DateTime value.
103 \note You should not base timeout calculations on this
104 absolute time value. Clock time is guaranteed to be
105 monotonous, absolute time may be non-monotonous if
106 the system date/time is changed. */
108 static reltime_type reltime(clock_type clock); ///< Convert clock to relative time
109 /**< This member converts a clock value into a relative
110 Boost.DateTime time interval
111 \note The resolution of reltime_type might be smaller
112 than the clock_type resolution */
114 static clock_type clock(abstime_type time); ///< Convert absolute time to clock value
115 /**< This member convert an absolute time value into the
116 corresponding clock value.
119 static clock_type from_time_t(time_t const & time);
120 ///< Convert legacy time_t to clock value
121 /**< This member converts an absolute time value
122 represented as a time_t value into a clock value */
124 static clock_type from_timeval(timeval const & time);
125 ///< Convert legacy timeval to clock value
126 /**< This member converts an absolute time value
127 represented as a timeval value into a clock value */
129 static clock_type nanoseconds(int64_type v); ///< Convert \a v nanoseconds to clock_type
130 static clock_type microseconds(int64_type v); ///< Convert \a v microseconds to clock_type
131 static clock_type milliseconds(int64_type v); ///< Convert \a v milliseconds to clock_type
132 static clock_type seconds(int64_type v); ///< Convert \a v seconds to clock_type
133 static clock_type minutes(int64_type v); ///< Convert \a v minutes to clock_type
134 static clock_type hours(int64_type v); ///< Convert \a v hours to clock_type
135 static clock_type days(int64_type v); ///< Convert \a v days to clock_type
137 static int64_type in_nanoseconds(clock_type v); ///< Convert \a v to nanoseconds
138 static int64_type in_microseconds(clock_type v); ///< Convert \a v to microseconds
139 static int64_type in_milliseconds(clock_type v); ///< Convert \a v to milliseconds
140 static int64_type in_seconds(clock_type v); ///< Convert \a v to seconds
141 static int64_type in_minutes(clock_type v); ///< Convert \a v to minutes
142 static int64_type in_hours(clock_type v); ///< Convert \a v to hours
143 static int64_type in_days(clock_type v); ///< Convert \a v to days
145 static void restart(); ///< Force re-synchronization of abstime and clock
146 /**< Calling the member should never be necessary since
147 abstime() / clock() automatically call restart() if
153 abstime_type abstime_m(clock_type clock);
154 clock_type clock_m(abstime_type time);
157 boost::posix_time::ptime baseAbstime_;
158 clock_type baseClock_;
160 /// Internal: ClockService private data (PIMPL idiom)
163 friend class singleton<ClockService>;
167 /** \brief Console argument parser to parse value as time interval
169 This parser will parse a time interval specification into a ClockService::clock_type
170 value. The following units are supported:
172 <table class="senf fixedcolumn">
173 <tr><td>\c d</td><td>days</td></tr>
174 <tr><td>\c h</td><td>hours</td></tr>
175 <tr><td>\c m</td><td>minutes</td></tr>
176 <tr><td>\c s</td><td>seconds</td></tr>
179 Additionally, the unit may be prefixed by an SI scale:
181 <table class="senf fixedcolumn">
182 <tr><td>\c m</td><td>milli</td></tr>
183 <tr><td>\c u</td><td>micro</td></tr>
184 <tr><td>\c n</td><td>nano</td></tr>
187 An optional decimal point is also supported. A single timer interval may combine any number
188 of these specifications. The following are all valid intervals:
190 <table class="senf fixedcolumn">
191 <tr><td><code>10d</code></td><td>10 days</td></tr>
192 <tr><td><code>5d5d</code></td><td>10 days</td></tr>
193 <tr><td><code>1d2h100m3.5s</code></td><td>27 hours, 30 minutes and 3.5 seconds</td></tr>
194 <tr><td><code>1s100ms</code></td><td>1.1 seconds</td></tr>
195 <tr><td><code>1.1s</code></td><td>1.1 seconds</td></tr>
196 <tr><td><code>123.456us</code></td><td>123.456 microseconds</td></tr>
197 <tr><td><code>2md</code></td><td>(very unusual) 2 milli-days</td></tr>
200 void parseClockServiceInterval(console::ParseCommandInfo::TokensRange const & tokens,
201 ClockService::clock_type & out);
203 void formatClockServiceInterval(ClockService::clock_type interval, std::ostream & os);
206 ///////////////////////////////hh.e////////////////////////////////////////
207 #include "ClockService.cci"
208 //#include "ClockService.ct"
209 //#include "ClockService.cti"
216 // comment-column: 40
217 // c-file-style: "senf"
218 // indent-tabs-mode: nil
219 // ispell-local-dictionary: "american"
220 // compile-command: "scons -u test"