ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
tickconverter.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of the \aliblong. It does not belong to an \alibmod and is
4/// included in any \alibbuild.
5///
6/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
7/// Published under \ref mainpage_license "Boost Software License".
8//==================================================================================================
9ALIB_EXPORT namespace alib { namespace time {
10
11//==================================================================================================
12/// As explained in detail in the documentation of the module \alib_time, a steady time model is
13/// supported with class \alib{time;Ticks} and a non-steady one representing the system clock with
14/// class \alib{time;DateTime}.
15/// Only values of the latter type can be converted to human-readable (calendar) date and time values.
16///
17/// In some situations however,software that requires steady, monotonic time points, may also be
18/// required to present these time points in human-readable format. It is possible to do some sort
19/// of conversion. For that, simply both clocks need to be probed at the same point
20/// in time and then time points of both notions can be put in relation to these two probes.
21///
22/// The effect, however, is that the conversion results will change for all values as soon as
23/// the system clock is changed and the probe values of the two clocks are updated.
24/// This is true also for values that are "older" than the point in time that the clock change
25/// happened. The reason is quickly understood: The system clock's counter changes, while the steady
26/// clock's counter does not.
27///
28/// To give the user of \alib full control about how system clock changes are reflected,
29/// the conversion of time points is encapsulated by this class together with one pair of clock probe
30/// data. software can use one ore more instances of this class and update (synchronize) these
31/// instances independently.
32//==================================================================================================
34{
35 protected:
36 /// Time point of steady clock of last invocation of #SyncClocks.
38
39 /// Time point of system clock of last invocation of #SyncClocks.
41
42 public:
43 //==========================================================================================
44 /// Constructor. Invokes #SyncClocks.
45 //==========================================================================================
47 {
48 SyncClocks();
49 }
50
51 //==========================================================================================
52 /// Generates a set of "probes" of the steady, monotonic clock and the system clock.
53 /// The measurement of both clocks is repeated the given number of times and the pair with
54 /// the smallest difference between both is chosen.
55 /// This approach mitigates the risk of using a pair for which thread execution had been
56 /// interrupted during the two measurements.
57 ///
58 /// Note that after a call to this method, the conversion methods may return slightly
59 /// different values than before the call, even if the system clock was not changed.
60 ///
61 /// If this method is not invoked after a change of the system clock, such change of the
62 /// system clock is not reflected by the conversion methods.
63 /// In other words, the conversion methods always work just as if the system clock had not
64 /// changed since the last invocation of this method.
65 ///
66 /// \note
67 /// On a GNU/Linux workstation (without workload), the error observed when doing only one
68 /// measurement was in the magnitude of several microseconds.
69 ///
70 /// @param qtyRepeats The number of measurements to perform. Defaults to \c 5.
71 //==========================================================================================
73 void SyncClocks( int qtyRepeats = 5 );
74
75 //==========================================================================================
76 /// Sets the pair of conversion times to equal the other converter object. This is useful
77 /// to avoid differences in conversion across converter instances used in software.
78 ///
79 /// @param other Another converter object to copy the synchronization information from.
80 //==========================================================================================
86
87 //==========================================================================================
88 /// Converts a \b %Ticks object to a \b %DateTime object.
89 /// @param ticks The ticks object to convert.
90 /// @return The date time object.
91 //==========================================================================================
93 {
95 + std::chrono::duration_cast<std::chrono::system_clock::duration>(
96 ticks.Export() - steadyClockSyncTime ) );
97 }
98
99 //==========================================================================================
100 /// Converts a \b %DateTime object to a \b %Ticks object.
101 /// @param dateTime The date/time object to convert.
102 /// @return The date time object.
103 //==========================================================================================
105 {
106 return Ticks( dateTime.Export() - systemClockSyncTime + steadyClockSyncTime);
107 }
108};
109
110
111} // namespace alib[::time]
112
113/// Type alias in namespace \b alib.
115
116} // namespace [alib]
117
DateTime ToDateTime(Ticks ticks)
DateTime::TTimePoint systemClockSyncTime
Time point of system clock of last invocation of SyncClocks.
void SetAs(const TickConverter &other)
Ticks::TTimePoint steadyClockSyncTime
Time point of steady clock of last invocation of SyncClocks.
ALIB_DLL void SyncClocks(int qtyRepeats=5)
TickConverter()
Constructor. Invokes SyncClocks.
Ticks ToTicks(DateTime dateTime)
TTimePoint Export() const
typename std::chrono::steady_clock::time_point TTimePoint
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
time::DateTime DateTime
Type alias in namespace alib.
Definition datetime.inl:224
time::Ticks Ticks
Type alias in namespace alib.
Definition ticks.inl:109
time::TickConverter TickConverter
Type alias in namespace alib.