task_environment.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477
  1. // Copyright 2017 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_TEST_TASK_ENVIRONMENT_H_
  5. #define BASE_TEST_TASK_ENVIRONMENT_H_
  6. #include <memory>
  7. #include "base/compiler_specific.h"
  8. #include "base/memory/ref_counted.h"
  9. #include "base/observer_list_types.h"
  10. #include "base/task/lazy_thread_pool_task_runner.h"
  11. #include "base/task/sequence_manager/sequence_manager.h"
  12. #include "base/task/single_thread_task_runner.h"
  13. #include "base/test/scoped_run_loop_timeout.h"
  14. #include "base/threading/thread_checker.h"
  15. #include "base/time/time.h"
  16. #include "base/traits_bag.h"
  17. #include "build/build_config.h"
  18. namespace base {
  19. class Clock;
  20. class FileDescriptorWatcher;
  21. class SimpleTaskExecutor;
  22. class TickClock;
  23. namespace subtle {
  24. class ScopedTimeClockOverrides;
  25. }
  26. namespace test {
  27. // This header exposes SingleThreadTaskEnvironment and TaskEnvironment.
  28. //
  29. // SingleThreadTaskEnvironment enables the following APIs within its scope:
  30. // - (Thread|Sequenced)TaskRunnerHandle on the main thread
  31. // - RunLoop on the main thread
  32. //
  33. // TaskEnvironment additionally enables:
  34. // - posting to base::ThreadPool through base/task/thread_pool.h.
  35. //
  36. // Hint: For content::BrowserThreads, use content::BrowserTaskEnvironment.
  37. //
  38. // Tests should prefer SingleThreadTaskEnvironment over TaskEnvironment when the
  39. // former is sufficient.
  40. //
  41. // Tasks posted to the (Thread|Sequenced)TaskRunnerHandle run synchronously when
  42. // RunLoop::Run(UntilIdle) or TaskEnvironment::RunUntilIdle is called on the
  43. // main thread.
  44. //
  45. // The TaskEnvironment requires TestTimeouts::Initialize() to be called in order
  46. // to run posted tasks, so that it can watch for problematic long-running tasks.
  47. //
  48. // The TimeSource trait can be used to request that delayed tasks be under the
  49. // manual control of RunLoop::Run() and TaskEnvironment::FastForward*() methods.
  50. //
  51. // If a TaskEnvironment's ThreadPoolExecutionMode is QUEUED, ThreadPool tasks
  52. // run when RunUntilIdle() or ~TaskEnvironment is called. If
  53. // ThreadPoolExecutionMode is ASYNC, they run as they are posted.
  54. //
  55. // All TaskEnvironment methods must be called from the main thread.
  56. //
  57. // Usage:
  58. //
  59. // class MyTestFixture : public testing::Test {
  60. // public:
  61. // (...)
  62. //
  63. // // protected rather than private visibility will allow controlling the
  64. // // task environment (e.g. RunUntilIdle(), FastForwardBy(), etc.). from the
  65. // // test body.
  66. // protected:
  67. // // Must generally be the first member to be initialized first and
  68. // // destroyed last (some members that require single-threaded
  69. // // initialization and tear down may need to come before -- e.g.
  70. // // base::test::ScopedFeatureList). Extra traits, like TimeSource, are
  71. // // best provided inline when declaring the TaskEnvironment, as
  72. // // such:
  73. // base::test::TaskEnvironment task_environment_{
  74. // base::test::TaskEnvironment::TimeSource::MOCK_TIME};
  75. //
  76. // // Other members go here (or further below in private section.)
  77. // };
  78. class TaskEnvironment {
  79. protected:
  80. // This enables a two-phase initialization for sub classes such as
  81. // content::BrowserTaskEnvironment which need to provide the default task
  82. // queue because they instantiate a scheduler on the same thread. Subclasses
  83. // using this trait must invoke DeferredInitFromSubclass() before running the
  84. // task environment.
  85. struct SubclassCreatesDefaultTaskRunner {};
  86. public:
  87. enum class TimeSource {
  88. // Delayed tasks and Time/TimeTicks::Now() use the real-time system clock.
  89. SYSTEM_TIME,
  90. // Delayed tasks use a mock clock which only advances when reaching "idle"
  91. // during a RunLoop::Run() call on the main thread or a FastForward*() call
  92. // to this TaskEnvironment. "idle" is defined as the main thread and thread
  93. // pool being out of ready tasks. In that situation : time advances to the
  94. // soonest delay between main thread and thread pool delayed tasks,
  95. // according to the semantics of the current Run*() or FastForward*() call.
  96. //
  97. // This also mocks Time/TimeTicks::Now() with the same mock clock.
  98. // Time::Now() and TimeTicks::Now() (with respect to its origin) start
  99. // without submillisecond components.
  100. //
  101. // Warning some platform APIs are still real-time, e.g.:
  102. // * PlatformThread::Sleep
  103. // * WaitableEvent::TimedWait
  104. // * ConditionVariable::TimedWait
  105. // * Delayed tasks on unmanaged base::Thread's and other custom task
  106. // runners.
  107. MOCK_TIME,
  108. DEFAULT = SYSTEM_TIME
  109. };
  110. // This type will determine what types of messages will get pumped by the main
  111. // thread.
  112. // Note: If your test needs to use a custom MessagePump you should
  113. // consider using a SingleThreadTaskExecutor instead.
  114. enum class MainThreadType {
  115. // The main thread doesn't pump system messages.
  116. DEFAULT,
  117. // The main thread pumps UI messages.
  118. UI,
  119. // The main thread pumps asynchronous IO messages and supports the
  120. // FileDescriptorWatcher API on POSIX.
  121. IO,
  122. };
  123. // Note that this is irrelevant (and ignored) under
  124. // ThreadingMode::MAIN_THREAD_ONLY
  125. enum class ThreadPoolExecutionMode {
  126. // Thread pool tasks are queued and only executed when RunUntilIdle(),
  127. // FastForwardBy(), or FastForwardUntilNoTasksRemain() are explicitly
  128. // called. Note: RunLoop::Run() does *not* unblock the ThreadPool in this
  129. // mode (it strictly runs only the main thread).
  130. QUEUED,
  131. // Thread pool tasks run as they are posted. RunUntilIdle() can still be
  132. // used to block until done.
  133. // Note that regardless of this trait, delayed tasks are always "queued"
  134. // under TimeSource::MOCK_TIME mode.
  135. ASYNC,
  136. DEFAULT = ASYNC
  137. };
  138. enum class ThreadingMode {
  139. // ThreadPool will be initialized, thus adding support for multi-threaded
  140. // tests.
  141. MULTIPLE_THREADS,
  142. // No thread pool will be initialized. Useful for tests that want to run
  143. // single threaded. Prefer using SingleThreadTaskEnvironment over this
  144. // trait.
  145. MAIN_THREAD_ONLY,
  146. DEFAULT = MULTIPLE_THREADS
  147. };
  148. // On Windows, sets the COM environment for the ThreadPoolInstance. Ignored
  149. // on other platforms.
  150. enum class ThreadPoolCOMEnvironment {
  151. // Do not initialize COM for the pool's workers.
  152. NONE,
  153. // Place the pool's workers in a COM MTA.
  154. COM_MTA,
  155. // Enable the MTA by default in unit tests to match the browser process's
  156. // ThreadPoolInstance configuration.
  157. //
  158. // This has the adverse side-effect of enabling the MTA in non-browser unit
  159. // tests as well but the downside there is not as bad as not having it in
  160. // browser unit tests. It just means some COM asserts may pass in unit
  161. // tests where they wouldn't in integration tests or prod. That's okay
  162. // because unit tests are already generally very loose on allowing I/O,
  163. // waits, etc. Such misuse will still be caught in later phases (and COM
  164. // usage should already be pretty much inexistent in sandboxed processes).
  165. DEFAULT = COM_MTA,
  166. };
  167. // List of traits that are valid inputs for the constructor below.
  168. struct ValidTraits {
  169. ValidTraits(TimeSource);
  170. ValidTraits(MainThreadType);
  171. ValidTraits(ThreadPoolExecutionMode);
  172. ValidTraits(SubclassCreatesDefaultTaskRunner);
  173. ValidTraits(ThreadingMode);
  174. ValidTraits(ThreadPoolCOMEnvironment);
  175. };
  176. // Constructor accepts zero or more traits which customize the testing
  177. // environment.
  178. template <typename... TaskEnvironmentTraits,
  179. class CheckArgumentsAreValid = std::enable_if_t<
  180. trait_helpers::AreValidTraits<ValidTraits,
  181. TaskEnvironmentTraits...>::value>>
  182. NOINLINE explicit TaskEnvironment(TaskEnvironmentTraits... traits)
  183. : TaskEnvironment(
  184. trait_helpers::GetEnum<TimeSource, TimeSource::DEFAULT>(traits...),
  185. trait_helpers::GetEnum<MainThreadType, MainThreadType::DEFAULT>(
  186. traits...),
  187. trait_helpers::GetEnum<ThreadPoolExecutionMode,
  188. ThreadPoolExecutionMode::DEFAULT>(traits...),
  189. trait_helpers::GetEnum<ThreadingMode, ThreadingMode::DEFAULT>(
  190. traits...),
  191. trait_helpers::GetEnum<ThreadPoolCOMEnvironment,
  192. ThreadPoolCOMEnvironment::DEFAULT>(
  193. traits...),
  194. trait_helpers::HasTrait<SubclassCreatesDefaultTaskRunner,
  195. TaskEnvironmentTraits...>(),
  196. trait_helpers::NotATraitTag()) {}
  197. TaskEnvironment(const TaskEnvironment&) = delete;
  198. TaskEnvironment& operator=(const TaskEnvironment&) = delete;
  199. // Waits until no undelayed ThreadPool tasks remain. Then, unregisters the
  200. // ThreadPoolInstance and the (Thread|Sequenced)TaskRunnerHandle.
  201. virtual ~TaskEnvironment();
  202. // Returns a TaskRunner that schedules tasks on the main thread.
  203. scoped_refptr<base::SingleThreadTaskRunner> GetMainThreadTaskRunner();
  204. // Returns whether the main thread's TaskRunner has pending tasks. This will
  205. // always return true if called right after RunUntilIdle.
  206. bool MainThreadIsIdle() const;
  207. // Runs tasks until both the (Thread|Sequenced)TaskRunnerHandle and the
  208. // ThreadPool's non-delayed queues are empty.
  209. // While RunUntilIdle() is quite practical and sometimes even necessary -- for
  210. // example, to flush all tasks bound to Unretained() state before destroying
  211. // test members -- it should be used with caution per the following warnings:
  212. //
  213. // WARNING #1: This may run long (flakily timeout) and even never return! Do
  214. // not use this when repeating tasks such as animated web pages
  215. // are present.
  216. // WARNING #2: This may return too early! For example, if used to run until an
  217. // incoming event has occurred but that event depends on a task in
  218. // a different queue -- e.g. a standalone base::Thread or a system
  219. // event.
  220. //
  221. // As such, prefer RunLoop::Run() with an explicit RunLoop::QuitClosure() when
  222. // possible.
  223. void RunUntilIdle();
  224. // Only valid for instances using TimeSource::MOCK_TIME. Fast-forwards
  225. // virtual time by |delta|, causing all tasks on the main thread and thread
  226. // pool with a remaining delay less than or equal to |delta| to be executed in
  227. // their natural order before this returns. |delta| must be non-negative. Upon
  228. // returning from this method, NowTicks() will be >= the initial |NowTicks() +
  229. // delta|. It is guaranteed to be == iff tasks executed in this
  230. // FastForwardBy() didn't result in nested calls to time-advancing-methods.
  231. void FastForwardBy(TimeDelta delta);
  232. // Only valid for instances using TimeSource::MOCK_TIME.
  233. // Short for FastForwardBy(TimeDelta::Max()).
  234. //
  235. // WARNING: This has the same caveat as RunUntilIdle() and is even more likely
  236. // to spin forever (any RepeatingTimer will cause this).
  237. void FastForwardUntilNoTasksRemain();
  238. // Only valid for instances using TimeSource::MOCK_TIME. Advances virtual time
  239. // by |delta|. Unlike FastForwardBy, this does not run tasks. Prefer
  240. // FastForwardBy() when possible but this can be useful when testing blocked
  241. // pending tasks where being idle (required to fast-forward) is not possible.
  242. //
  243. // Delayed tasks that are ripe as a result of this will be scheduled.
  244. // RunUntilIdle() can be used after this call to ensure those tasks have run.
  245. // Note: AdvanceClock(delta) + RunUntilIdle() is slightly different from
  246. // FastForwardBy(delta) in that time passes instantly before running any task
  247. // (whereas FastForwardBy() will advance the clock in the smallest increments
  248. // possible at a time). Hence FastForwardBy() is more realistic but
  249. // AdvanceClock() can be useful when testing edge case scenarios that
  250. // specifically handle more time than expected to have passed.
  251. void AdvanceClock(TimeDelta delta);
  252. // Only valid for instances using TimeSource::MOCK_TIME. Returns a
  253. // TickClock whose time is updated by FastForward(By|UntilNoTasksRemain).
  254. const TickClock* GetMockTickClock() const;
  255. // Only valid for instances using TimeSource::MOCK_TIME. Returns a
  256. // Clock whose time is updated by FastForward(By|UntilNoTasksRemain). The
  257. // initial value is implementation defined and should be queried by tests that
  258. // depend on it.
  259. // TickClock should be used instead of Clock to measure elapsed time in a
  260. // process. See time.h.
  261. const Clock* GetMockClock() const;
  262. // Only valid for instances using TimeSource::MOCK_TIME. Returns the current
  263. // virtual tick time (based on a realistic Now(), sampled when this
  264. // TaskEnvironment was created, and manually advanced from that point on).
  265. // This is always equivalent to base::TimeTicks::Now() under
  266. // TimeSource::MOCK_TIME.
  267. base::TimeTicks NowTicks() const;
  268. // Only valid for instances using TimeSource::MOCK_TIME. Returns the number of
  269. // pending tasks (delayed and non-delayed) of the main thread's TaskRunner.
  270. // When debugging, you can use DescribeCurrentTasks() to see what those are.
  271. size_t GetPendingMainThreadTaskCount() const;
  272. // Only valid for instances using TimeSource::MOCK_TIME.
  273. // Returns the delay until the next pending task of the main thread's
  274. // TaskRunner if there is one, otherwise it returns TimeDelta::Max().
  275. TimeDelta NextMainThreadPendingTaskDelay() const;
  276. // Only valid for instances using TimeSource::MOCK_TIME.
  277. // Returns true iff the next task is delayed. Returns false if the next task
  278. // is immediate or if there is no next task.
  279. bool NextTaskIsDelayed() const;
  280. // For debugging purposes: Dumps information about pending tasks on the main
  281. // thread, and currently running tasks on the thread pool.
  282. void DescribeCurrentTasks() const;
  283. // Detach ThreadCheckers (will rebind on next usage), useful for the odd test
  284. // suite which doesn't run on the main thread but still has exclusive access
  285. // to driving this TaskEnvironment (e.g. WaylandClientTestSuiteServer).
  286. void DetachFromThread();
  287. class TestTaskTracker;
  288. // Callers outside of TaskEnvironment may not use the returned pointer. They
  289. // should just use base::ThreadPoolInstance::Get().
  290. static TestTaskTracker* CreateThreadPool();
  291. class DestructionObserver : public CheckedObserver {
  292. public:
  293. DestructionObserver() = default;
  294. ~DestructionObserver() override = default;
  295. DestructionObserver(const DestructionObserver&) = delete;
  296. DestructionObserver& operator=(const DestructionObserver&) = delete;
  297. virtual void WillDestroyCurrentTaskEnvironment() = 0;
  298. };
  299. // Adds/removes a DestructionObserver to any TaskEnvironment. Observers are
  300. // notified when any TaskEnvironment goes out of scope (other than with a move
  301. // operation). Must be called on the main thread.
  302. static void AddDestructionObserver(DestructionObserver* observer);
  303. static void RemoveDestructionObserver(DestructionObserver* observer);
  304. // Instantiating a ParallelExecutionFence waits for all currently running
  305. // ThreadPool tasks before the constructor returns and from then on prevents
  306. // additional tasks from running during its lifetime.
  307. //
  308. // Must be instantiated from the test main thread.
  309. class ParallelExecutionFence {
  310. public:
  311. // Instantiates a ParallelExecutionFence, crashes with an optional
  312. // |error_message| if not invoked from test main thread.
  313. explicit ParallelExecutionFence(const char* error_message = "");
  314. ~ParallelExecutionFence();
  315. ParallelExecutionFence(const ParallelExecutionFence&) = delete;
  316. ParallelExecutionFence& operator=(const ParallelExecutionFence& other) =
  317. delete;
  318. private:
  319. bool previously_allowed_to_run_ = false;
  320. };
  321. // The number of foreground workers in the ThreadPool managed by a
  322. // TaskEnvironment instance. This can be used to determine the maximum
  323. // parallelism in tests that require each parallel task it spawns to be
  324. // running at once. Having multiple threads prevents deadlocks should some
  325. // blocking APIs not use ScopedBlockingCall. It also allows enough concurrency
  326. // to allow TSAN to spot data races.
  327. static constexpr int kNumForegroundThreadPoolThreads = 4;
  328. protected:
  329. explicit TaskEnvironment(TaskEnvironment&& other);
  330. constexpr MainThreadType main_thread_type() const {
  331. return main_thread_type_;
  332. }
  333. constexpr ThreadPoolExecutionMode thread_pool_execution_mode() const {
  334. return thread_pool_execution_mode_;
  335. }
  336. // Returns the MockTimeDomain driving this TaskEnvironment if this instance is
  337. // using TimeSource::MOCK_TIME, nullptr otherwise.
  338. sequence_manager::TimeDomain* GetMockTimeDomain() const;
  339. sequence_manager::SequenceManager* sequence_manager() const;
  340. void DeferredInitFromSubclass(
  341. scoped_refptr<base::SingleThreadTaskRunner> task_runner);
  342. // Derived classes may need to control when the task environment goes away
  343. // (e.g. ~FooTaskEnvironment() may want to effectively trigger
  344. // ~TaskEnvironment() before its members are destroyed).
  345. void DestroyTaskEnvironment();
  346. private:
  347. class MockTimeDomain;
  348. void InitializeThreadPool();
  349. void DestroyThreadPool();
  350. void CompleteInitialization();
  351. // The template constructor has to be in the header but it delegates to this
  352. // constructor to initialize all other members out-of-line.
  353. TaskEnvironment(TimeSource time_source,
  354. MainThreadType main_thread_type,
  355. ThreadPoolExecutionMode thread_pool_execution_mode,
  356. ThreadingMode threading_mode,
  357. ThreadPoolCOMEnvironment thread_pool_com_environment,
  358. bool subclass_creates_default_taskrunner,
  359. trait_helpers::NotATraitTag tag);
  360. const MainThreadType main_thread_type_;
  361. const ThreadPoolExecutionMode thread_pool_execution_mode_;
  362. const ThreadingMode threading_mode_;
  363. const ThreadPoolCOMEnvironment thread_pool_com_environment_;
  364. const bool subclass_creates_default_taskrunner_;
  365. std::unique_ptr<sequence_manager::SequenceManager> sequence_manager_;
  366. // Manages the clock under TimeSource::MOCK_TIME modes. Null in
  367. // TimeSource::SYSTEM_TIME mode.
  368. std::unique_ptr<MockTimeDomain> mock_time_domain_;
  369. // Overrides Time/TimeTicks::Now() under TimeSource::MOCK_TIME mode.
  370. // Null in other modes.
  371. std::unique_ptr<subtle::ScopedTimeClockOverrides> time_overrides_;
  372. scoped_refptr<sequence_manager::TaskQueue> task_queue_;
  373. scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
  374. // Only set for instances using TimeSource::MOCK_TIME.
  375. std::unique_ptr<Clock> mock_clock_;
  376. #if BUILDFLAG(IS_POSIX) || BUILDFLAG(IS_FUCHSIA)
  377. // Enables the FileDescriptorWatcher API iff running a MainThreadType::IO.
  378. std::unique_ptr<FileDescriptorWatcher> file_descriptor_watcher_;
  379. #endif
  380. // Owned by the ThreadPoolInstance.
  381. TestTaskTracker* task_tracker_ = nullptr;
  382. // Ensures destruction of lazy TaskRunners when this is destroyed.
  383. std::unique_ptr<base::internal::ScopedLazyTaskRunnerListForTesting>
  384. scoped_lazy_task_runner_list_for_testing_;
  385. // Sets RunLoop::Run() to LOG(FATAL) if not Quit() in a timely manner.
  386. std::unique_ptr<ScopedRunLoopTimeout> run_loop_timeout_;
  387. std::unique_ptr<bool> owns_instance_ = std::make_unique<bool>(true);
  388. // To support base::CurrentThread().
  389. std::unique_ptr<SimpleTaskExecutor> simple_task_executor_;
  390. // Used to verify thread-affinity of operations that must occur on the main
  391. // thread. This is the case for anything that modifies or drives the
  392. // |sequence_manager_|.
  393. THREAD_CHECKER(main_thread_checker_);
  394. };
  395. // SingleThreadTaskEnvironment takes the same traits as TaskEnvironment and is
  396. // used the exact same way. It's a short-form for
  397. // TaskEnvironment{TaskEnvironment::ThreadingMode::MAIN_THREAD_ONLY, ...};
  398. class SingleThreadTaskEnvironment : public TaskEnvironment {
  399. public:
  400. template <class... ArgTypes>
  401. SingleThreadTaskEnvironment(ArgTypes... args)
  402. : TaskEnvironment(ThreadingMode::MAIN_THREAD_ONLY, args...) {}
  403. };
  404. } // namespace test
  405. } // namespace base
  406. #endif // BASE_TEST_TASK_ENVIRONMENT_H_