xref: /aosp_15_r20/external/abseil-cpp/absl/synchronization/internal/kernel_timeout.h (revision 9356374a3709195abf420251b3e825997ff56c0f)
1*9356374aSAndroid Build Coastguard Worker // Copyright 2017 The Abseil Authors.
2*9356374aSAndroid Build Coastguard Worker //
3*9356374aSAndroid Build Coastguard Worker // Licensed under the Apache License, Version 2.0 (the "License");
4*9356374aSAndroid Build Coastguard Worker // you may not use this file except in compliance with the License.
5*9356374aSAndroid Build Coastguard Worker // You may obtain a copy of the License at
6*9356374aSAndroid Build Coastguard Worker //
7*9356374aSAndroid Build Coastguard Worker //      https://www.apache.org/licenses/LICENSE-2.0
8*9356374aSAndroid Build Coastguard Worker //
9*9356374aSAndroid Build Coastguard Worker // Unless required by applicable law or agreed to in writing, software
10*9356374aSAndroid Build Coastguard Worker // distributed under the License is distributed on an "AS IS" BASIS,
11*9356374aSAndroid Build Coastguard Worker // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12*9356374aSAndroid Build Coastguard Worker // See the License for the specific language governing permissions and
13*9356374aSAndroid Build Coastguard Worker // limitations under the License.
14*9356374aSAndroid Build Coastguard Worker 
15*9356374aSAndroid Build Coastguard Worker #ifndef ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
16*9356374aSAndroid Build Coastguard Worker #define ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
17*9356374aSAndroid Build Coastguard Worker 
18*9356374aSAndroid Build Coastguard Worker #ifndef _WIN32
19*9356374aSAndroid Build Coastguard Worker #include <sys/types.h>
20*9356374aSAndroid Build Coastguard Worker #endif
21*9356374aSAndroid Build Coastguard Worker 
22*9356374aSAndroid Build Coastguard Worker #include <algorithm>
23*9356374aSAndroid Build Coastguard Worker #include <chrono>  // NOLINT(build/c++11)
24*9356374aSAndroid Build Coastguard Worker #include <cstdint>
25*9356374aSAndroid Build Coastguard Worker #include <ctime>
26*9356374aSAndroid Build Coastguard Worker #include <limits>
27*9356374aSAndroid Build Coastguard Worker 
28*9356374aSAndroid Build Coastguard Worker #include "absl/base/config.h"
29*9356374aSAndroid Build Coastguard Worker #include "absl/base/internal/raw_logging.h"
30*9356374aSAndroid Build Coastguard Worker #include "absl/time/clock.h"
31*9356374aSAndroid Build Coastguard Worker #include "absl/time/time.h"
32*9356374aSAndroid Build Coastguard Worker 
33*9356374aSAndroid Build Coastguard Worker namespace absl {
34*9356374aSAndroid Build Coastguard Worker ABSL_NAMESPACE_BEGIN
35*9356374aSAndroid Build Coastguard Worker namespace synchronization_internal {
36*9356374aSAndroid Build Coastguard Worker 
37*9356374aSAndroid Build Coastguard Worker // An optional timeout, with nanosecond granularity.
38*9356374aSAndroid Build Coastguard Worker //
39*9356374aSAndroid Build Coastguard Worker // This is a private low-level API for use by a handful of low-level
40*9356374aSAndroid Build Coastguard Worker // components. Higher-level components should build APIs based on
41*9356374aSAndroid Build Coastguard Worker // absl::Time and absl::Duration.
42*9356374aSAndroid Build Coastguard Worker class KernelTimeout {
43*9356374aSAndroid Build Coastguard Worker  public:
44*9356374aSAndroid Build Coastguard Worker   // Construct an absolute timeout that should expire at `t`.
45*9356374aSAndroid Build Coastguard Worker   explicit KernelTimeout(absl::Time t);
46*9356374aSAndroid Build Coastguard Worker 
47*9356374aSAndroid Build Coastguard Worker   // Construct a relative timeout that should expire after `d`.
48*9356374aSAndroid Build Coastguard Worker   explicit KernelTimeout(absl::Duration d);
49*9356374aSAndroid Build Coastguard Worker 
50*9356374aSAndroid Build Coastguard Worker   // Infinite timeout.
KernelTimeout()51*9356374aSAndroid Build Coastguard Worker   constexpr KernelTimeout() : rep_(kNoTimeout) {}
52*9356374aSAndroid Build Coastguard Worker 
53*9356374aSAndroid Build Coastguard Worker   // A more explicit factory for those who prefer it.
54*9356374aSAndroid Build Coastguard Worker   // Equivalent to `KernelTimeout()`.
Never()55*9356374aSAndroid Build Coastguard Worker   static constexpr KernelTimeout Never() { return KernelTimeout(); }
56*9356374aSAndroid Build Coastguard Worker 
57*9356374aSAndroid Build Coastguard Worker   // Returns true if there is a timeout that will eventually expire.
58*9356374aSAndroid Build Coastguard Worker   // Returns false if the timeout is infinite.
has_timeout()59*9356374aSAndroid Build Coastguard Worker   bool has_timeout() const { return rep_ != kNoTimeout; }
60*9356374aSAndroid Build Coastguard Worker 
61*9356374aSAndroid Build Coastguard Worker   // If `has_timeout()` is true, returns true if the timeout was provided as an
62*9356374aSAndroid Build Coastguard Worker   // `absl::Time`. The return value is undefined if `has_timeout()` is false
63*9356374aSAndroid Build Coastguard Worker   // because all indefinite timeouts are equivalent.
is_absolute_timeout()64*9356374aSAndroid Build Coastguard Worker   bool is_absolute_timeout() const { return (rep_ & 1) == 0; }
65*9356374aSAndroid Build Coastguard Worker 
66*9356374aSAndroid Build Coastguard Worker   // If `has_timeout()` is true, returns true if the timeout was provided as an
67*9356374aSAndroid Build Coastguard Worker   // `absl::Duration`. The return value is undefined if `has_timeout()` is false
68*9356374aSAndroid Build Coastguard Worker   // because all indefinite timeouts are equivalent.
is_relative_timeout()69*9356374aSAndroid Build Coastguard Worker   bool is_relative_timeout() const { return (rep_ & 1) == 1; }
70*9356374aSAndroid Build Coastguard Worker 
71*9356374aSAndroid Build Coastguard Worker   // Convert to `struct timespec` for interfaces that expect an absolute
72*9356374aSAndroid Build Coastguard Worker   // timeout. If !has_timeout() or is_relative_timeout(), attempts to convert to
73*9356374aSAndroid Build Coastguard Worker   // a reasonable absolute timeout, but callers should to test has_timeout() and
74*9356374aSAndroid Build Coastguard Worker   // is_relative_timeout() and prefer to use a more appropriate interface.
75*9356374aSAndroid Build Coastguard Worker   struct timespec MakeAbsTimespec() const;
76*9356374aSAndroid Build Coastguard Worker 
77*9356374aSAndroid Build Coastguard Worker   // Convert to `struct timespec` for interfaces that expect a relative
78*9356374aSAndroid Build Coastguard Worker   // timeout. If !has_timeout() or is_absolute_timeout(), attempts to convert to
79*9356374aSAndroid Build Coastguard Worker   // a reasonable relative timeout, but callers should to test has_timeout() and
80*9356374aSAndroid Build Coastguard Worker   // is_absolute_timeout() and prefer to use a more appropriate interface. Since
81*9356374aSAndroid Build Coastguard Worker   // the return value is a relative duration, it should be recomputed by calling
82*9356374aSAndroid Build Coastguard Worker   // this method in the case of a spurious wakeup.
83*9356374aSAndroid Build Coastguard Worker   struct timespec MakeRelativeTimespec() const;
84*9356374aSAndroid Build Coastguard Worker 
85*9356374aSAndroid Build Coastguard Worker #ifndef _WIN32
86*9356374aSAndroid Build Coastguard Worker   // Convert to `struct timespec` for interfaces that expect an absolute timeout
87*9356374aSAndroid Build Coastguard Worker   // on a specific clock `c`. This is similar to `MakeAbsTimespec()`, but
88*9356374aSAndroid Build Coastguard Worker   // callers usually want to use this method with `CLOCK_MONOTONIC` when
89*9356374aSAndroid Build Coastguard Worker   // relative timeouts are requested, and when the appropriate interface expects
90*9356374aSAndroid Build Coastguard Worker   // an absolute timeout relative to a specific clock (for example,
91*9356374aSAndroid Build Coastguard Worker   // pthread_cond_clockwait() or sem_clockwait()). If !has_timeout(), attempts
92*9356374aSAndroid Build Coastguard Worker   // to convert to a reasonable absolute timeout, but callers should to test
93*9356374aSAndroid Build Coastguard Worker   // has_timeout() prefer to use a more appropriate interface.
94*9356374aSAndroid Build Coastguard Worker   struct timespec MakeClockAbsoluteTimespec(clockid_t c) const;
95*9356374aSAndroid Build Coastguard Worker #endif
96*9356374aSAndroid Build Coastguard Worker 
97*9356374aSAndroid Build Coastguard Worker   // Convert to unix epoch nanos for interfaces that expect an absolute timeout
98*9356374aSAndroid Build Coastguard Worker   // in nanoseconds. If !has_timeout() or is_relative_timeout(), attempts to
99*9356374aSAndroid Build Coastguard Worker   // convert to a reasonable absolute timeout, but callers should to test
100*9356374aSAndroid Build Coastguard Worker   // has_timeout() and is_relative_timeout() and prefer to use a more
101*9356374aSAndroid Build Coastguard Worker   // appropriate interface.
102*9356374aSAndroid Build Coastguard Worker   int64_t MakeAbsNanos() const;
103*9356374aSAndroid Build Coastguard Worker 
104*9356374aSAndroid Build Coastguard Worker   // Converts to milliseconds from now, or INFINITE when
105*9356374aSAndroid Build Coastguard Worker   // !has_timeout(). For use by SleepConditionVariableSRW on
106*9356374aSAndroid Build Coastguard Worker   // Windows. Callers should recognize that the return value is a
107*9356374aSAndroid Build Coastguard Worker   // relative duration (it should be recomputed by calling this method
108*9356374aSAndroid Build Coastguard Worker   // in the case of a spurious wakeup).
109*9356374aSAndroid Build Coastguard Worker   // This header file may be included transitively by public header files,
110*9356374aSAndroid Build Coastguard Worker   // so we define our own DWORD and INFINITE instead of getting them from
111*9356374aSAndroid Build Coastguard Worker   // <intsafe.h> and <WinBase.h>.
112*9356374aSAndroid Build Coastguard Worker   typedef unsigned long DWord;  // NOLINT
113*9356374aSAndroid Build Coastguard Worker   DWord InMillisecondsFromNow() const;
114*9356374aSAndroid Build Coastguard Worker 
115*9356374aSAndroid Build Coastguard Worker   // Convert to std::chrono::time_point for interfaces that expect an absolute
116*9356374aSAndroid Build Coastguard Worker   // timeout, like std::condition_variable::wait_until(). If !has_timeout() or
117*9356374aSAndroid Build Coastguard Worker   // is_relative_timeout(), attempts to convert to a reasonable absolute
118*9356374aSAndroid Build Coastguard Worker   // timeout, but callers should test has_timeout() and is_relative_timeout()
119*9356374aSAndroid Build Coastguard Worker   // and prefer to use a more appropriate interface.
120*9356374aSAndroid Build Coastguard Worker   std::chrono::time_point<std::chrono::system_clock> ToChronoTimePoint() const;
121*9356374aSAndroid Build Coastguard Worker 
122*9356374aSAndroid Build Coastguard Worker   // Convert to std::chrono::time_point for interfaces that expect a relative
123*9356374aSAndroid Build Coastguard Worker   // timeout, like std::condition_variable::wait_for(). If !has_timeout() or
124*9356374aSAndroid Build Coastguard Worker   // is_absolute_timeout(), attempts to convert to a reasonable relative
125*9356374aSAndroid Build Coastguard Worker   // timeout, but callers should test has_timeout() and is_absolute_timeout()
126*9356374aSAndroid Build Coastguard Worker   // and prefer to use a more appropriate interface. Since the return value is a
127*9356374aSAndroid Build Coastguard Worker   // relative duration, it should be recomputed by calling this method in the
128*9356374aSAndroid Build Coastguard Worker   // case of a spurious wakeup.
129*9356374aSAndroid Build Coastguard Worker   std::chrono::nanoseconds ToChronoDuration() const;
130*9356374aSAndroid Build Coastguard Worker 
131*9356374aSAndroid Build Coastguard Worker   // Returns true if steady (aka monotonic) clocks are supported by the system.
132*9356374aSAndroid Build Coastguard Worker   // This method exists because go/btm requires synchronized clocks, and
133*9356374aSAndroid Build Coastguard Worker   // thus requires we use the system (aka walltime) clock.
SupportsSteadyClock()134*9356374aSAndroid Build Coastguard Worker   static constexpr bool SupportsSteadyClock() { return true; }
135*9356374aSAndroid Build Coastguard Worker 
136*9356374aSAndroid Build Coastguard Worker  private:
137*9356374aSAndroid Build Coastguard Worker   // Returns the current time, expressed as a count of nanoseconds since the
138*9356374aSAndroid Build Coastguard Worker   // epoch used by an arbitrary clock. The implementation tries to use a steady
139*9356374aSAndroid Build Coastguard Worker   // (monotonic) clock if one is available.
140*9356374aSAndroid Build Coastguard Worker   static int64_t SteadyClockNow();
141*9356374aSAndroid Build Coastguard Worker 
142*9356374aSAndroid Build Coastguard Worker   // Internal representation.
143*9356374aSAndroid Build Coastguard Worker   //   - If the value is kNoTimeout, then the timeout is infinite, and
144*9356374aSAndroid Build Coastguard Worker   //     has_timeout() will return true.
145*9356374aSAndroid Build Coastguard Worker   //   - If the low bit is 0, then the high 63 bits is the number of nanoseconds
146*9356374aSAndroid Build Coastguard Worker   //     after the unix epoch.
147*9356374aSAndroid Build Coastguard Worker   //   - If the low bit is 1, then the high 63 bits is the number of nanoseconds
148*9356374aSAndroid Build Coastguard Worker   //     after the epoch used by SteadyClockNow().
149*9356374aSAndroid Build Coastguard Worker   //
150*9356374aSAndroid Build Coastguard Worker   // In all cases the time is stored as an absolute time, the only difference is
151*9356374aSAndroid Build Coastguard Worker   // the clock epoch. The use of absolute times is important since in the case
152*9356374aSAndroid Build Coastguard Worker   // of a relative timeout with a spurious wakeup, the program would have to
153*9356374aSAndroid Build Coastguard Worker   // restart the wait, and thus needs a way of recomputing the remaining time.
154*9356374aSAndroid Build Coastguard Worker   uint64_t rep_;
155*9356374aSAndroid Build Coastguard Worker 
156*9356374aSAndroid Build Coastguard Worker   // Returns the number of nanoseconds stored in the internal representation.
157*9356374aSAndroid Build Coastguard Worker   // When combined with the clock epoch indicated by the low bit (which is
158*9356374aSAndroid Build Coastguard Worker   // accessed through is_absolute_timeout() and is_relative_timeout()), the
159*9356374aSAndroid Build Coastguard Worker   // return value is used to compute when the timeout should occur.
RawAbsNanos()160*9356374aSAndroid Build Coastguard Worker   int64_t RawAbsNanos() const { return static_cast<int64_t>(rep_ >> 1); }
161*9356374aSAndroid Build Coastguard Worker 
162*9356374aSAndroid Build Coastguard Worker   // Converts to nanoseconds from now. Since the return value is a relative
163*9356374aSAndroid Build Coastguard Worker   // duration, it should be recomputed by calling this method in the case of a
164*9356374aSAndroid Build Coastguard Worker   // spurious wakeup.
165*9356374aSAndroid Build Coastguard Worker   int64_t InNanosecondsFromNow() const;
166*9356374aSAndroid Build Coastguard Worker 
167*9356374aSAndroid Build Coastguard Worker   // A value that represents no timeout (or an infinite timeout).
168*9356374aSAndroid Build Coastguard Worker   static constexpr uint64_t kNoTimeout = (std::numeric_limits<uint64_t>::max)();
169*9356374aSAndroid Build Coastguard Worker 
170*9356374aSAndroid Build Coastguard Worker   // The maximum value that can be stored in the high 63 bits.
171*9356374aSAndroid Build Coastguard Worker   static constexpr int64_t kMaxNanos = (std::numeric_limits<int64_t>::max)();
172*9356374aSAndroid Build Coastguard Worker };
173*9356374aSAndroid Build Coastguard Worker 
174*9356374aSAndroid Build Coastguard Worker }  // namespace synchronization_internal
175*9356374aSAndroid Build Coastguard Worker ABSL_NAMESPACE_END
176*9356374aSAndroid Build Coastguard Worker }  // namespace absl
177*9356374aSAndroid Build Coastguard Worker 
178*9356374aSAndroid Build Coastguard Worker #endif  // ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
179