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
47namespace absl {
48namespace base_internal {
49
50// -----------------------------------------------------------------------------
51// CycleClock
52// -----------------------------------------------------------------------------
53class CycleClock {
54 public:
55 // CycleClock::Now()
56 //
57 // Returns the value of a cycle counter that counts at a rate that is
58 // approximately constant.
59 static int64_t Now();
60
61 // CycleClock::Frequency()
62 //
63 // Returns the amount by which `CycleClock::Now()` increases per second. Note
64 // that this value may not necessarily match the core CPU clock frequency.
65 static double Frequency();
66
67 private:
68 CycleClock() = delete; // no instances
69 CycleClock(const CycleClock&) = delete;
70 CycleClock& operator=(const CycleClock&) = delete;
71};
72
73using CycleClockSourceFunc = int64_t (*)();
74
75class CycleClockSource {
76 private:
77 // CycleClockSource::Register()
78 //
79 // Register a function that provides an alternate source for the unscaled CPU
80 // cycle count value. The source function must be async signal safe, must not
81 // call CycleClock::Now(), and must have a frequency that matches that of the
82 // unscaled clock used by CycleClock. A nullptr value resets CycleClock to use
83 // the default source.
84 static void Register(CycleClockSourceFunc source);
85};
86
87} // namespace base_internal
88} // namespace absl
89
90#endif // ABSL_BASE_INTERNAL_CYCLECLOCK_H_
91