1 //
2 // Copyright 2017 The Abseil Authors.
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //      https://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 
17 // -----------------------------------------------------------------------------
18 // File: cycleclock.h
19 // -----------------------------------------------------------------------------
20 //
21 // This header file defines a `CycleClock`, which yields the value and frequency
22 // of a cycle counter that increments at a rate that is approximately constant.
23 //
24 // NOTE:
25 //
26 // The cycle counter frequency is not necessarily related to the core clock
27 // frequency and should not be treated as such. That is, `CycleClock` cycles are
28 // not necessarily "CPU cycles" and code should not rely on that behavior, even
29 // if experimentally observed.
30 //
31 // An arbitrary offset may have been added to the counter at power on.
32 //
33 // On some platforms, the rate and offset of the counter may differ
34 // slightly when read from different CPUs of a multiprocessor. Usually,
35 // we try to ensure that the operating system adjusts values periodically
36 // so that values agree approximately.   If you need stronger guarantees,
37 // consider using alternate interfaces.
38 //
39 // The CPU is not required to maintain the ordering of a cycle counter read
40 // with respect to surrounding instructions.
41 
42 #ifndef ABSL_BASE_INTERNAL_CYCLECLOCK_H_
43 #define ABSL_BASE_INTERNAL_CYCLECLOCK_H_
44 
45 #include <cstdint>
46 
47 #include "absl/base/config.h"
48 
49 namespace absl {
50 ABSL_NAMESPACE_BEGIN
51 namespace base_internal {
52 
53 // -----------------------------------------------------------------------------
54 // CycleClock
55 // -----------------------------------------------------------------------------
56 class CycleClock {
57  public:
58   // CycleClock::Now()
59   //
60   // Returns the value of a cycle counter that counts at a rate that is
61   // approximately constant.
62   static int64_t Now();
63 
64   // CycleClock::Frequency()
65   //
66   // Returns the amount by which `CycleClock::Now()` increases per second. Note
67   // that this value may not necessarily match the core CPU clock frequency.
68   static double Frequency();
69 
70  private:
71   CycleClock() = delete;  // no instances
72   CycleClock(const CycleClock&) = delete;
73   CycleClock& operator=(const CycleClock&) = delete;
74 };
75 
76 using CycleClockSourceFunc = int64_t (*)();
77 
78 class CycleClockSource {
79  private:
80   // CycleClockSource::Register()
81   //
82   // Register a function that provides an alternate source for the unscaled CPU
83   // cycle count value. The source function must be async signal safe, must not
84   // call CycleClock::Now(), and must have a frequency that matches that of the
85   // unscaled clock used by CycleClock. A nullptr value resets CycleClock to use
86   // the default source.
87   static void Register(CycleClockSourceFunc source);
88 };
89 
90 }  // namespace base_internal
91 ABSL_NAMESPACE_END
92 }  // namespace absl
93 
94 #endif  // ABSL_BASE_INTERNAL_CYCLECLOCK_H_
95