1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15
16 // An optional absolute timeout, with nanosecond granularity,
17 // compatible with absl::Time. Suitable for in-register
18 // parameter-passing (e.g. syscalls.)
19 // Constructible from a absl::Time (for a timeout to be respected) or {}
20 // (for "no timeout".)
21 // This is a private low-level API for use by a handful of low-level
22 // components that are friends of this class. Higher-level components
23 // should build APIs based on absl::Time and absl::Duration.
24
25 #ifndef ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
26 #define ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
27
28 #include <time.h>
29
30 #include <algorithm>
31 #include <limits>
32
33 #include "absl/base/internal/raw_logging.h"
34 #include "absl/time/clock.h"
35 #include "absl/time/time.h"
36
37 namespace absl {
38 ABSL_NAMESPACE_BEGIN
39 namespace synchronization_internal {
40
41 class Futex;
42 class Waiter;
43
44 class KernelTimeout {
45 public:
46 // A timeout that should expire at <t>. Any value, in the full
47 // InfinitePast() to InfiniteFuture() range, is valid here and will be
48 // respected.
KernelTimeout(absl::Time t)49 explicit KernelTimeout(absl::Time t) : ns_(MakeNs(t)) {}
50 // No timeout.
KernelTimeout()51 KernelTimeout() : ns_(0) {}
52
53 // A more explicit factory for those who prefer it. Equivalent to {}.
Never()54 static KernelTimeout Never() { return {}; }
55
56 // We explicitly do not support other custom formats: timespec, int64_t nanos.
57 // Unify on this and absl::Time, please.
58
has_timeout()59 bool has_timeout() const { return ns_ != 0; }
60
61 // Convert to parameter for sem_timedwait/futex/similar. Only for approved
62 // users. Do not call if !has_timeout.
63 struct timespec MakeAbsTimespec();
64
65 private:
66 // internal rep, not user visible: ns after unix epoch.
67 // zero = no timeout.
68 // Negative we treat as an unlikely (and certainly expired!) but valid
69 // timeout.
70 int64_t ns_;
71
MakeNs(absl::Time t)72 static int64_t MakeNs(absl::Time t) {
73 // optimization--InfiniteFuture is common "no timeout" value
74 // and cheaper to compare than convert.
75 if (t == absl::InfiniteFuture()) return 0;
76 int64_t x = ToUnixNanos(t);
77
78 // A timeout that lands exactly on the epoch (x=0) needs to be respected,
79 // so we alter it unnoticably to 1. Negative timeouts are in
80 // theory supported, but handled poorly by the kernel (long
81 // delays) so push them forward too; since all such times have
82 // already passed, it's indistinguishable.
83 if (x <= 0) x = 1;
84 // A time larger than what can be represented to the kernel is treated
85 // as no timeout.
86 if (x == (std::numeric_limits<int64_t>::max)()) x = 0;
87 return x;
88 }
89
90 #ifdef _WIN32
91 // Converts to milliseconds from now, or INFINITE when
92 // !has_timeout(). For use by SleepConditionVariableSRW on
93 // Windows. Callers should recognize that the return value is a
94 // relative duration (it should be recomputed by calling this method
95 // in the case of a spurious wakeup).
96 // This header file may be included transitively by public header files,
97 // so we define our own DWORD and INFINITE instead of getting them from
98 // <intsafe.h> and <WinBase.h>.
99 typedef unsigned long DWord; // NOLINT
InMillisecondsFromNow()100 DWord InMillisecondsFromNow() const {
101 constexpr DWord kInfinite = (std::numeric_limits<DWord>::max)();
102 if (!has_timeout()) {
103 return kInfinite;
104 }
105 // The use of absl::Now() to convert from absolute time to
106 // relative time means that absl::Now() cannot use anything that
107 // depends on KernelTimeout (for example, Mutex) on Windows.
108 int64_t now = ToUnixNanos(absl::Now());
109 if (ns_ >= now) {
110 // Round up so that Now() + ms_from_now >= ns_.
111 constexpr uint64_t max_nanos =
112 (std::numeric_limits<int64_t>::max)() - 999999u;
113 uint64_t ms_from_now =
114 (std::min<uint64_t>(max_nanos, ns_ - now) + 999999u) / 1000000u;
115 if (ms_from_now > kInfinite) {
116 return kInfinite;
117 }
118 return static_cast<DWord>(ms_from_now);
119 }
120 return 0;
121 }
122 #endif
123
124 friend class Futex;
125 friend class Waiter;
126 };
127
MakeAbsTimespec()128 inline struct timespec KernelTimeout::MakeAbsTimespec() {
129 int64_t n = ns_;
130 static const int64_t kNanosPerSecond = 1000 * 1000 * 1000;
131 if (n == 0) {
132 ABSL_RAW_LOG(
133 ERROR, "Tried to create a timespec from a non-timeout; never do this.");
134 // But we'll try to continue sanely. no-timeout ~= saturated timeout.
135 n = (std::numeric_limits<int64_t>::max)();
136 }
137
138 // Kernel APIs validate timespecs as being at or after the epoch,
139 // despite the kernel time type being signed. However, no one can
140 // tell the difference between a timeout at or before the epoch (since
141 // all such timeouts have expired!)
142 if (n < 0) n = 0;
143
144 struct timespec abstime;
145 int64_t seconds = (std::min)(n / kNanosPerSecond,
146 int64_t{(std::numeric_limits<time_t>::max)()});
147 abstime.tv_sec = static_cast<time_t>(seconds);
148 abstime.tv_nsec = static_cast<decltype(abstime.tv_nsec)>(n % kNanosPerSecond);
149 return abstime;
150 }
151
152 } // namespace synchronization_internal
153 ABSL_NAMESPACE_END
154 } // namespace absl
155
156 #endif // ABSL_SYNCHRONIZATION_INTERNAL_KERNEL_TIMEOUT_H_
157