1 // Copyright 2013 The Flutter 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 5 #ifndef FLUTTER_TESTING_THREAD_TEST_H_ 6 #define FLUTTER_TESTING_THREAD_TEST_H_ 7 8 #include <memory> 9 #include <string> 10 11 #include "flutter/fml/macros.h" 12 #include "flutter/fml/message_loop.h" 13 #include "flutter/fml/task_runner.h" 14 #include "flutter/fml/thread.h" 15 #include "gtest/gtest.h" 16 17 namespace flutter { 18 namespace testing { 19 20 //------------------------------------------------------------------------------ 21 /// @brief A fixture that creates threads with running message loops that 22 /// are terminated when the test is done (the threads are joined 23 /// then as well). While this fixture may be used on it's own, it is 24 /// often sub-classed but other fixtures whose functioning requires 25 /// threads to be created as necessary. 26 /// 27 class ThreadTest : public ::testing::Test { 28 public: 29 //---------------------------------------------------------------------------- 30 /// @brief Get the task runner for the thread that the current unit-test 31 /// is running on. The creates a message loop is necessary. 32 /// 33 /// @attention Unlike all other threads and task runners, this task runner is 34 /// shared by all tests running in the process. Tests must ensure 35 /// that all tasks posted to this task runner are executed before 36 /// the test ends to prevent the task from one test being executed 37 /// while another test is running. When in doubt, just create a 38 /// bespoke thread and task running. These cannot be seen by other 39 /// tests in the process. 40 /// 41 /// @see `GetThreadTaskRunner`, `CreateNewThread`. 42 /// 43 /// @return The task runner for the thread the test is running on. 44 /// 45 fml::RefPtr<fml::TaskRunner> GetCurrentTaskRunner(); 46 47 //---------------------------------------------------------------------------- 48 /// @brief Get the task runner for a dedicated thread created for this 49 /// test instance by this fixture. This threads message loop will 50 /// be terminated and the thread joined when the test is done. 51 /// 52 /// @attention Prefer using the `CreateNewThread` call. 53 /// 54 /// @bug This is an older call that should probably be deprecated and 55 /// eventually removed from use. It is redundant now that the 56 /// `CreateNewThread` call allows tests to create new threads (and 57 /// name them to boot) as necessary. 58 /// 59 /// @return The task runner for a dedicated thread created for the test. 60 /// 61 fml::RefPtr<fml::TaskRunner> GetThreadTaskRunner(); 62 63 //---------------------------------------------------------------------------- 64 /// @brief Creates a new thread, initializes a message loop on it, and, 65 /// returns its task runner to the unit-test. The message loop is 66 /// terminated (and its thread joined) when the test ends. This 67 /// allows tests to create multiple named threads as necessary. 68 /// 69 /// @param[in] name The name of the OS thread created. 70 /// 71 /// @return The task runner for the newly created thread. 72 /// 73 fml::RefPtr<fml::TaskRunner> CreateNewThread(std::string name = ""); 74 75 protected: 76 // |testing::Test| 77 void SetUp() override; 78 79 // |testing::Test| 80 void TearDown() override; 81 82 private: 83 std::unique_ptr<fml::Thread> thread_; 84 fml::RefPtr<fml::TaskRunner> thread_task_runner_; 85 fml::RefPtr<fml::TaskRunner> current_task_runner_; 86 std::vector<std::unique_ptr<fml::Thread>> extra_threads_; 87 }; 88 89 } // namespace testing 90 } // namespace flutter 91 92 #endif // FLUTTER_TESTING_THREAD_TEST_H_ 93