2 * Copyright 2017 Facebook, Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 #include <boost/noncopyable.hpp>
25 #include <folly/portability/Unistd.h>
27 namespace folly { namespace detail {
29 enum class FutexResult {
30 VALUE_CHANGED, /* Futex value didn't match expected */
31 AWOKEN, /* futex wait matched with a futex wake */
32 INTERRUPTED, /* Spurious wake-up or signal caused futex wait failure */
37 * Futex is an atomic 32 bit unsigned integer that provides access to the
38 * futex() syscall on that value. It is templated in such a way that it
39 * can interact properly with DeterministicSchedule testing.
41 * If you don't know how to use futex(), you probably shouldn't be using
42 * this class. Even if you do know how, you should have a good reason
43 * (and benchmarks to back you up).
45 template <template <typename> class Atom = std::atomic>
46 struct Futex : Atom<uint32_t>, boost::noncopyable {
48 explicit Futex(uint32_t init = 0) : Atom<uint32_t>(init) {}
50 /** Puts the thread to sleep if this->load() == expected. Returns true when
51 * it is returning because it has consumed a wake() event, false for any
52 * other return (signal, this->load() != expected, or spurious wakeup). */
53 bool futexWait(uint32_t expected, uint32_t waitMask = -1) {
54 auto rv = futexWaitImpl(expected, nullptr, nullptr, waitMask);
55 assert(rv != FutexResult::TIMEDOUT);
56 return rv == FutexResult::AWOKEN;
59 /** Similar to futexWait but also accepts a timeout that gives the time until
60 * when the call can block (time is the absolute time i.e time since epoch).
61 * Allowed clock types: std::chrono::system_clock, std::chrono::steady_clock.
62 * Returns one of FutexResult values.
64 * NOTE: On some systems steady_clock is just an alias for system_clock,
65 * and is not actually steady.*/
66 template <class Clock, class Duration = typename Clock::duration>
67 FutexResult futexWaitUntil(
69 const std::chrono::time_point<Clock, Duration>& absTime,
70 uint32_t waitMask = -1) {
71 using std::chrono::duration_cast;
72 using std::chrono::nanoseconds;
73 using std::chrono::seconds;
74 using std::chrono::steady_clock;
75 using std::chrono::system_clock;
76 using std::chrono::time_point;
79 (std::is_same<Clock, system_clock>::value ||
80 std::is_same<Clock, steady_clock>::value),
81 "futexWaitUntil only knows std::chrono::{system_clock,steady_clock}");
82 assert((std::is_same<Clock, system_clock>::value) || Clock::is_steady);
84 // We launder the clock type via a std::chrono::duration so that we
85 // can compile both the true and false branch. Tricky case is when
86 // steady_clock has a higher precision than system_clock (Xcode 6,
87 // for example), for which time_point<system_clock> construction
88 // refuses to do an implicit duration conversion. (duration is
89 // happy to implicitly convert its denominator causing overflow, but
90 // refuses conversion that might cause truncation.) We use explicit
91 // duration_cast to work around this. Truncation does not actually
92 // occur (unless Duration != Clock::duration) because the missing
93 // implicit conversion is in the untaken branch.
94 Duration absTimeDuration = absTime.time_since_epoch();
95 if (std::is_same<Clock, system_clock>::value) {
96 time_point<system_clock> absSystemTime(
97 duration_cast<system_clock::duration>(absTimeDuration));
98 return futexWaitImpl(expected, &absSystemTime, nullptr, waitMask);
100 time_point<steady_clock> absSteadyTime(
101 duration_cast<steady_clock::duration>(absTimeDuration));
102 return futexWaitImpl(expected, nullptr, &absSteadyTime, waitMask);
106 /** Wakens up to count waiters where (waitMask & wakeMask) !=
107 * 0, returning the number of awoken threads, or -1 if an error
108 * occurred. Note that when constructing a concurrency primitive
109 * that can guard its own destruction, it is likely that you will
110 * want to ignore EINVAL here (as well as making sure that you
111 * never touch the object after performing the memory store that
112 * is the linearization point for unlock or control handoff).
113 * See https://sourceware.org/bugzilla/show_bug.cgi?id=13690 */
114 int futexWake(int count = std::numeric_limits<int>::max(),
115 uint32_t wakeMask = -1);
119 /** Underlying implementation of futexWait and futexWaitUntil.
120 * At most one of absSystemTime and absSteadyTime should be non-null.
121 * Timeouts are separated into separate parameters to allow the
122 * implementations to be elsewhere without templating on the clock
123 * type, which is otherwise complicated by the fact that steady_clock
124 * is the same as system_clock on some platforms. */
125 FutexResult futexWaitImpl(
127 std::chrono::time_point<std::chrono::system_clock>* absSystemTime,
128 std::chrono::time_point<std::chrono::steady_clock>* absSteadyTime,
132 /** A std::atomic subclass that can be used to force Futex to emulate
133 * the underlying futex() syscall. This is primarily useful to test or
134 * benchmark the emulated implementation on systems that don't need it. */
135 template <typename T>
136 struct EmulatedFutexAtomic : public std::atomic<T> {
137 EmulatedFutexAtomic() noexcept = default;
138 constexpr /* implicit */ EmulatedFutexAtomic(T init) noexcept
139 : std::atomic<T>(init) {}
140 // It doesn't copy or move
141 EmulatedFutexAtomic(EmulatedFutexAtomic&& rhs) = delete;
144 /* Available specializations, with definitions elsewhere */
147 int Futex<std::atomic>::futexWake(int count, uint32_t wakeMask);
150 FutexResult Futex<std::atomic>::futexWaitImpl(
152 std::chrono::time_point<std::chrono::system_clock>* absSystemTime,
153 std::chrono::time_point<std::chrono::steady_clock>* absSteadyTime,
157 int Futex<EmulatedFutexAtomic>::futexWake(int count, uint32_t wakeMask);
160 FutexResult Futex<EmulatedFutexAtomic>::futexWaitImpl(
162 std::chrono::time_point<std::chrono::system_clock>* absSystemTime,
163 std::chrono::time_point<std::chrono::steady_clock>* absSteadyTime,