1 // Copyright 2018 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_TIME_TIME_OVERRIDE_H_ 6 #define BASE_TIME_TIME_OVERRIDE_H_ 7 8 #include <atomic> 9 #include <optional> 10 11 #include "base/base_export.h" 12 #include "base/time/time.h" 13 #include "build/build_config.h" 14 15 namespace base { 16 17 using TimeNowFunction = decltype(&Time::Now); 18 using TimeTicksNowFunction = decltype(&TimeTicks::Now); 19 using LiveTicksNowFunction = decltype(&LiveTicks::Now); 20 using ThreadTicksNowFunction = decltype(&ThreadTicks::Now); 21 22 // Time overrides should be used with extreme caution. Discuss with //base/time 23 // OWNERS before adding a new one. 24 namespace subtle { 25 26 // Override the return value of Time::Now and Time::NowFromSystemTime / 27 // TimeTicks::Now / LiveTicks::Now / ThreadTicks::Now to emulate time, e.g. for 28 // tests or to modify progression of time. It is recommended that the override 29 // be set while single-threaded and before the first call to Now() to avoid 30 // threading issues and inconsistencies in returned values. Overriding time 31 // while other threads are running is very subtle and should be reserved for 32 // developer only use cases (e.g. virtual time in devtools) where any flakiness 33 // caused by a racy time update isn't surprising. Instantiating a 34 // ScopedTimeClockOverrides while other threads are running might break their 35 // expectation that TimeTicks and ThreadTicks increase monotonically. Nested 36 // overrides are not allowed. 37 class BASE_EXPORT ScopedTimeClockOverrides { 38 public: 39 // Pass |nullptr| for any override if it shouldn't be overriden. 40 ScopedTimeClockOverrides(TimeNowFunction time_override, 41 TimeTicksNowFunction time_ticks_override, 42 ThreadTicksNowFunction thread_ticks_override, 43 LiveTicksNowFunction live_ticks_override = nullptr); 44 45 ScopedTimeClockOverrides(const ScopedTimeClockOverrides&) = delete; 46 ScopedTimeClockOverrides& operator=(const ScopedTimeClockOverrides&) = delete; 47 48 // Restores the platform default Now() functions. 49 ~ScopedTimeClockOverrides(); 50 overrides_active()51 static bool overrides_active() { return overrides_active_; } 52 53 private: 54 static bool overrides_active_; 55 }; 56 57 // These methods return the platform default Time::Now / TimeTicks::Now / 58 // ThreadTicks::Now values even while an override is in place. These methods 59 // should only be used in places where emulated time should be disregarded. For 60 // example, they can be used to implement test timeouts for tests that may 61 // override time. 62 BASE_EXPORT Time TimeNowIgnoringOverride(); 63 BASE_EXPORT Time TimeNowFromSystemTimeIgnoringOverride(); 64 BASE_EXPORT TimeTicks TimeTicksNowIgnoringOverride(); 65 BASE_EXPORT LiveTicks LiveTicksNowIgnoringOverride(); 66 BASE_EXPORT ThreadTicks ThreadTicksNowIgnoringOverride(); 67 68 #if BUILDFLAG(IS_POSIX) 69 // Equivalent to TimeTicksNowIgnoringOverride(), but is allowed to fail and 70 // return std::nullopt. This may safely be used in a signal handler. 71 BASE_EXPORT std::optional<TimeTicks> MaybeTimeTicksNowIgnoringOverride(); 72 #endif 73 74 } // namespace subtle 75 76 namespace internal { 77 78 // These function pointers are used by platform-independent implementations of 79 // the Now() methods and ScopedTimeClockOverrides. They are set to point to the 80 // respective NowIgnoringOverride functions by default, but can also be set by 81 // platform-specific code to select a default implementation at runtime, thereby 82 // avoiding the indirection via the NowIgnoringOverride functions. Note that the 83 // pointers can be overridden and later reset to the NowIgnoringOverride 84 // functions by ScopedTimeClockOverrides. 85 extern std::atomic<TimeNowFunction> g_time_now_function; 86 extern std::atomic<TimeNowFunction> g_time_now_from_system_time_function; 87 extern std::atomic<TimeTicksNowFunction> g_time_ticks_now_function; 88 extern std::atomic<LiveTicksNowFunction> g_live_ticks_now_function; 89 extern std::atomic<ThreadTicksNowFunction> g_thread_ticks_now_function; 90 91 } // namespace internal 92 93 } // namespace base 94 95 #endif // BASE_TIME_TIME_OVERRIDE_H_ 96