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
17namespace flutter {
18namespace 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 by other fixtures whose functioning requires
25/// threads to be created as necessary.
26///
27class ThreadTest : public ::testing::Test {
28 public:
29 ThreadTest();
30
31 //----------------------------------------------------------------------------
32 /// @brief Get the task runner for the thread that the current unit-test
33 /// is running on. This creates a message loop as necessary.
34 ///
35 /// @attention Unlike all other threads and task runners, this task runner is
36 /// shared by all tests running in the process. Tests must ensure
37 /// that all tasks posted to this task runner are executed before
38 /// the test ends to prevent the task from one test being executed
39 /// while another test is running. When in doubt, just create a
40 /// bespoke thread and task running. These cannot be seen by other
41 /// tests in the process.
42 ///
43 /// @see `GetThreadTaskRunner`, `CreateNewThread`.
44 ///
45 /// @return The task runner for the thread the test is running on.
46 ///
47 fml::RefPtr<fml::TaskRunner> GetCurrentTaskRunner();
48
49 //----------------------------------------------------------------------------
50 /// @brief Creates a new thread, initializes a message loop on it, and,
51 /// returns its task runner to the unit-test. The message loop is
52 /// terminated (and its thread joined) when the test ends. This
53 /// allows tests to create multiple named threads as necessary.
54 ///
55 /// @param[in] name The name of the OS thread created.
56 ///
57 /// @return The task runner for the newly created thread.
58 ///
59 fml::RefPtr<fml::TaskRunner> CreateNewThread(std::string name = "");
60
61 private:
62 fml::RefPtr<fml::TaskRunner> current_task_runner_;
63 std::vector<std::unique_ptr<fml::Thread>> extra_threads_;
64
65 FML_DISALLOW_COPY_AND_ASSIGN(ThreadTest);
66};
67
68} // namespace testing
69} // namespace flutter
70
71#endif // FLUTTER_TESTING_THREAD_TEST_H_
72