xref: /aosp_15_r20/external/libchrome/base/threading/simple_thread.h (revision 635a864187cb8b6c713ff48b7e790a6b21769273)
1*635a8641SAndroid Build Coastguard Worker // Copyright (c) 2011 The Chromium Authors. All rights reserved.
2*635a8641SAndroid Build Coastguard Worker // Use of this source code is governed by a BSD-style license that can be
3*635a8641SAndroid Build Coastguard Worker // found in the LICENSE file.
4*635a8641SAndroid Build Coastguard Worker 
5*635a8641SAndroid Build Coastguard Worker // WARNING: You should probably be using Thread (thread.h) instead.  Thread is
6*635a8641SAndroid Build Coastguard Worker //          Chrome's message-loop based Thread abstraction, and if you are a
7*635a8641SAndroid Build Coastguard Worker //          thread running in the browser, there will likely be assumptions
8*635a8641SAndroid Build Coastguard Worker //          that your thread will have an associated message loop.
9*635a8641SAndroid Build Coastguard Worker //
10*635a8641SAndroid Build Coastguard Worker // This is a simple thread interface that backs to a native operating system
11*635a8641SAndroid Build Coastguard Worker // thread.  You should use this only when you want a thread that does not have
12*635a8641SAndroid Build Coastguard Worker // an associated MessageLoop.  Unittesting is the best example of this.
13*635a8641SAndroid Build Coastguard Worker //
14*635a8641SAndroid Build Coastguard Worker // The simplest interface to use is DelegateSimpleThread, which will create
15*635a8641SAndroid Build Coastguard Worker // a new thread, and execute the Delegate's virtual Run() in this new thread
16*635a8641SAndroid Build Coastguard Worker // until it has completed, exiting the thread.
17*635a8641SAndroid Build Coastguard Worker //
18*635a8641SAndroid Build Coastguard Worker // NOTE: You *MUST* call Join on the thread to clean up the underlying thread
19*635a8641SAndroid Build Coastguard Worker // resources.  You are also responsible for destructing the SimpleThread object.
20*635a8641SAndroid Build Coastguard Worker // It is invalid to destroy a SimpleThread while it is running, or without
21*635a8641SAndroid Build Coastguard Worker // Start() having been called (and a thread never created).  The Delegate
22*635a8641SAndroid Build Coastguard Worker // object should live as long as a DelegateSimpleThread.
23*635a8641SAndroid Build Coastguard Worker //
24*635a8641SAndroid Build Coastguard Worker // Thread Safety: A SimpleThread is not completely thread safe.  It is safe to
25*635a8641SAndroid Build Coastguard Worker // access it from the creating thread or from the newly created thread.  This
26*635a8641SAndroid Build Coastguard Worker // implies that the creator thread should be the thread that calls Join.
27*635a8641SAndroid Build Coastguard Worker //
28*635a8641SAndroid Build Coastguard Worker // Example:
29*635a8641SAndroid Build Coastguard Worker //   class MyThreadRunner : public DelegateSimpleThread::Delegate { ... };
30*635a8641SAndroid Build Coastguard Worker //   MyThreadRunner runner;
31*635a8641SAndroid Build Coastguard Worker //   DelegateSimpleThread thread(&runner, "good_name_here");
32*635a8641SAndroid Build Coastguard Worker //   thread.Start();
33*635a8641SAndroid Build Coastguard Worker //   // Start will return after the Thread has been successfully started and
34*635a8641SAndroid Build Coastguard Worker //   // initialized.  The newly created thread will invoke runner->Run(), and
35*635a8641SAndroid Build Coastguard Worker //   // run until it returns.
36*635a8641SAndroid Build Coastguard Worker //   thread.Join();  // Wait until the thread has exited.  You *MUST* Join!
37*635a8641SAndroid Build Coastguard Worker //   // The SimpleThread object is still valid, however you may not call Join
38*635a8641SAndroid Build Coastguard Worker //   // or Start again.
39*635a8641SAndroid Build Coastguard Worker 
40*635a8641SAndroid Build Coastguard Worker #ifndef BASE_THREADING_SIMPLE_THREAD_H_
41*635a8641SAndroid Build Coastguard Worker #define BASE_THREADING_SIMPLE_THREAD_H_
42*635a8641SAndroid Build Coastguard Worker 
43*635a8641SAndroid Build Coastguard Worker #include <stddef.h>
44*635a8641SAndroid Build Coastguard Worker 
45*635a8641SAndroid Build Coastguard Worker #include <string>
46*635a8641SAndroid Build Coastguard Worker #include <vector>
47*635a8641SAndroid Build Coastguard Worker 
48*635a8641SAndroid Build Coastguard Worker #include "base/base_export.h"
49*635a8641SAndroid Build Coastguard Worker #include "base/compiler_specific.h"
50*635a8641SAndroid Build Coastguard Worker #include "base/containers/queue.h"
51*635a8641SAndroid Build Coastguard Worker #include "base/macros.h"
52*635a8641SAndroid Build Coastguard Worker #include "base/synchronization/lock.h"
53*635a8641SAndroid Build Coastguard Worker #include "base/synchronization/waitable_event.h"
54*635a8641SAndroid Build Coastguard Worker #include "base/threading/platform_thread.h"
55*635a8641SAndroid Build Coastguard Worker 
56*635a8641SAndroid Build Coastguard Worker namespace base {
57*635a8641SAndroid Build Coastguard Worker 
58*635a8641SAndroid Build Coastguard Worker // This is the base SimpleThread.  You can derive from it and implement the
59*635a8641SAndroid Build Coastguard Worker // virtual Run method, or you can use the DelegateSimpleThread interface.
60*635a8641SAndroid Build Coastguard Worker class BASE_EXPORT SimpleThread : public PlatformThread::Delegate {
61*635a8641SAndroid Build Coastguard Worker  public:
62*635a8641SAndroid Build Coastguard Worker   struct BASE_EXPORT Options {
63*635a8641SAndroid Build Coastguard Worker    public:
64*635a8641SAndroid Build Coastguard Worker     Options() = default;
OptionsOptions65*635a8641SAndroid Build Coastguard Worker     explicit Options(ThreadPriority priority_in) : priority(priority_in) {}
66*635a8641SAndroid Build Coastguard Worker     ~Options() = default;
67*635a8641SAndroid Build Coastguard Worker 
68*635a8641SAndroid Build Coastguard Worker     // Allow copies.
69*635a8641SAndroid Build Coastguard Worker     Options(const Options& other) = default;
70*635a8641SAndroid Build Coastguard Worker     Options& operator=(const Options& other) = default;
71*635a8641SAndroid Build Coastguard Worker 
72*635a8641SAndroid Build Coastguard Worker     // A custom stack size, or 0 for the system default.
73*635a8641SAndroid Build Coastguard Worker     size_t stack_size = 0;
74*635a8641SAndroid Build Coastguard Worker 
75*635a8641SAndroid Build Coastguard Worker     ThreadPriority priority = ThreadPriority::NORMAL;
76*635a8641SAndroid Build Coastguard Worker 
77*635a8641SAndroid Build Coastguard Worker     // If false, the underlying thread's PlatformThreadHandle will not be kept
78*635a8641SAndroid Build Coastguard Worker     // around and as such the SimpleThread instance will not be Join()able and
79*635a8641SAndroid Build Coastguard Worker     // must not be deleted before Run() is invoked. After that, it's up to
80*635a8641SAndroid Build Coastguard Worker     // the subclass to determine when it is safe to delete itself.
81*635a8641SAndroid Build Coastguard Worker     bool joinable = true;
82*635a8641SAndroid Build Coastguard Worker   };
83*635a8641SAndroid Build Coastguard Worker 
84*635a8641SAndroid Build Coastguard Worker   // Create a SimpleThread.  |options| should be used to manage any specific
85*635a8641SAndroid Build Coastguard Worker   // configuration involving the thread creation and management.
86*635a8641SAndroid Build Coastguard Worker   // Every thread has a name, in the form of |name_prefix|/TID, for example
87*635a8641SAndroid Build Coastguard Worker   // "my_thread/321".  The thread will not be created until Start() is called.
88*635a8641SAndroid Build Coastguard Worker   explicit SimpleThread(const std::string& name_prefix);
89*635a8641SAndroid Build Coastguard Worker   SimpleThread(const std::string& name_prefix, const Options& options);
90*635a8641SAndroid Build Coastguard Worker 
91*635a8641SAndroid Build Coastguard Worker   ~SimpleThread() override;
92*635a8641SAndroid Build Coastguard Worker 
93*635a8641SAndroid Build Coastguard Worker   // Starts the thread and returns only after the thread has started and
94*635a8641SAndroid Build Coastguard Worker   // initialized (i.e. ThreadMain() has been called).
95*635a8641SAndroid Build Coastguard Worker   void Start();
96*635a8641SAndroid Build Coastguard Worker 
97*635a8641SAndroid Build Coastguard Worker   // Joins the thread. If StartAsync() was used to start the thread, then this
98*635a8641SAndroid Build Coastguard Worker   // first waits for the thread to start cleanly, then it joins.
99*635a8641SAndroid Build Coastguard Worker   void Join();
100*635a8641SAndroid Build Coastguard Worker 
101*635a8641SAndroid Build Coastguard Worker   // Starts the thread, but returns immediately, without waiting for the thread
102*635a8641SAndroid Build Coastguard Worker   // to have initialized first (i.e. this does not wait for ThreadMain() to have
103*635a8641SAndroid Build Coastguard Worker   // been run first).
104*635a8641SAndroid Build Coastguard Worker   void StartAsync();
105*635a8641SAndroid Build Coastguard Worker 
106*635a8641SAndroid Build Coastguard Worker   // Subclasses should override the Run method.
107*635a8641SAndroid Build Coastguard Worker   virtual void Run() = 0;
108*635a8641SAndroid Build Coastguard Worker 
109*635a8641SAndroid Build Coastguard Worker   // Returns the thread id, only valid after the thread has started. If the
110*635a8641SAndroid Build Coastguard Worker   // thread was started using Start(), then this will be valid after the call to
111*635a8641SAndroid Build Coastguard Worker   // Start(). If StartAsync() was used to start the thread, then this must not
112*635a8641SAndroid Build Coastguard Worker   // be called before HasBeenStarted() returns True.
113*635a8641SAndroid Build Coastguard Worker   PlatformThreadId tid();
114*635a8641SAndroid Build Coastguard Worker 
115*635a8641SAndroid Build Coastguard Worker   // Returns True if the thread has been started and initialized (i.e. if
116*635a8641SAndroid Build Coastguard Worker   // ThreadMain() has run). If the thread was started with StartAsync(), but it
117*635a8641SAndroid Build Coastguard Worker   // hasn't been initialized yet (i.e. ThreadMain() has not run), then this will
118*635a8641SAndroid Build Coastguard Worker   // return False.
119*635a8641SAndroid Build Coastguard Worker   bool HasBeenStarted();
120*635a8641SAndroid Build Coastguard Worker 
121*635a8641SAndroid Build Coastguard Worker   // Returns True if Join() has ever been called.
HasBeenJoined()122*635a8641SAndroid Build Coastguard Worker   bool HasBeenJoined() { return joined_; }
123*635a8641SAndroid Build Coastguard Worker 
124*635a8641SAndroid Build Coastguard Worker   // Returns true if Start() or StartAsync() has been called.
HasStartBeenAttempted()125*635a8641SAndroid Build Coastguard Worker   bool HasStartBeenAttempted() { return start_called_; }
126*635a8641SAndroid Build Coastguard Worker 
127*635a8641SAndroid Build Coastguard Worker   // Overridden from PlatformThread::Delegate:
128*635a8641SAndroid Build Coastguard Worker   void ThreadMain() override;
129*635a8641SAndroid Build Coastguard Worker 
130*635a8641SAndroid Build Coastguard Worker  private:
131*635a8641SAndroid Build Coastguard Worker   // This is called just before the thread is started. This is called regardless
132*635a8641SAndroid Build Coastguard Worker   // of whether Start() or StartAsync() is used to start the thread.
BeforeStart()133*635a8641SAndroid Build Coastguard Worker   virtual void BeforeStart() {}
134*635a8641SAndroid Build Coastguard Worker 
135*635a8641SAndroid Build Coastguard Worker   // This is called just after the thread has been initialized and just before
136*635a8641SAndroid Build Coastguard Worker   // Run() is called. This is called on the newly started thread.
BeforeRun()137*635a8641SAndroid Build Coastguard Worker   virtual void BeforeRun() {}
138*635a8641SAndroid Build Coastguard Worker 
139*635a8641SAndroid Build Coastguard Worker   // This is called just before the thread is joined. The thread is started and
140*635a8641SAndroid Build Coastguard Worker   // has been initialized before this is called.
BeforeJoin()141*635a8641SAndroid Build Coastguard Worker   virtual void BeforeJoin() {}
142*635a8641SAndroid Build Coastguard Worker 
143*635a8641SAndroid Build Coastguard Worker   const std::string name_prefix_;
144*635a8641SAndroid Build Coastguard Worker   std::string name_;
145*635a8641SAndroid Build Coastguard Worker   const Options options_;
146*635a8641SAndroid Build Coastguard Worker   PlatformThreadHandle thread_;  // PlatformThread handle, reset after Join.
147*635a8641SAndroid Build Coastguard Worker   WaitableEvent event_;          // Signaled if Start() was ever called.
148*635a8641SAndroid Build Coastguard Worker   PlatformThreadId tid_ = kInvalidThreadId;  // The backing thread's id.
149*635a8641SAndroid Build Coastguard Worker   bool joined_ = false;                      // True if Join has been called.
150*635a8641SAndroid Build Coastguard Worker   // Set to true when the platform-thread creation has started.
151*635a8641SAndroid Build Coastguard Worker   bool start_called_ = false;
152*635a8641SAndroid Build Coastguard Worker 
153*635a8641SAndroid Build Coastguard Worker   DISALLOW_COPY_AND_ASSIGN(SimpleThread);
154*635a8641SAndroid Build Coastguard Worker };
155*635a8641SAndroid Build Coastguard Worker 
156*635a8641SAndroid Build Coastguard Worker // A SimpleThread which delegates Run() to its Delegate. Non-joinable
157*635a8641SAndroid Build Coastguard Worker // DelegateSimpleThread are safe to delete after Run() was invoked, their
158*635a8641SAndroid Build Coastguard Worker // Delegates are also safe to delete after that point from this class' point of
159*635a8641SAndroid Build Coastguard Worker // view (although implementations must of course make sure that Run() will not
160*635a8641SAndroid Build Coastguard Worker // use their Delegate's member state after its deletion).
161*635a8641SAndroid Build Coastguard Worker class BASE_EXPORT DelegateSimpleThread : public SimpleThread {
162*635a8641SAndroid Build Coastguard Worker  public:
163*635a8641SAndroid Build Coastguard Worker   class BASE_EXPORT Delegate {
164*635a8641SAndroid Build Coastguard Worker    public:
165*635a8641SAndroid Build Coastguard Worker     virtual ~Delegate() = default;
166*635a8641SAndroid Build Coastguard Worker     virtual void Run() = 0;
167*635a8641SAndroid Build Coastguard Worker   };
168*635a8641SAndroid Build Coastguard Worker 
169*635a8641SAndroid Build Coastguard Worker   DelegateSimpleThread(Delegate* delegate,
170*635a8641SAndroid Build Coastguard Worker                        const std::string& name_prefix);
171*635a8641SAndroid Build Coastguard Worker   DelegateSimpleThread(Delegate* delegate,
172*635a8641SAndroid Build Coastguard Worker                        const std::string& name_prefix,
173*635a8641SAndroid Build Coastguard Worker                        const Options& options);
174*635a8641SAndroid Build Coastguard Worker 
175*635a8641SAndroid Build Coastguard Worker   ~DelegateSimpleThread() override;
176*635a8641SAndroid Build Coastguard Worker   void Run() override;
177*635a8641SAndroid Build Coastguard Worker 
178*635a8641SAndroid Build Coastguard Worker  private:
179*635a8641SAndroid Build Coastguard Worker   Delegate* delegate_;
180*635a8641SAndroid Build Coastguard Worker 
181*635a8641SAndroid Build Coastguard Worker   DISALLOW_COPY_AND_ASSIGN(DelegateSimpleThread);
182*635a8641SAndroid Build Coastguard Worker };
183*635a8641SAndroid Build Coastguard Worker 
184*635a8641SAndroid Build Coastguard Worker // DelegateSimpleThreadPool allows you to start up a fixed number of threads,
185*635a8641SAndroid Build Coastguard Worker // and then add jobs which will be dispatched to the threads.  This is
186*635a8641SAndroid Build Coastguard Worker // convenient when you have a lot of small work that you want done
187*635a8641SAndroid Build Coastguard Worker // multi-threaded, but don't want to spawn a thread for each small bit of work.
188*635a8641SAndroid Build Coastguard Worker //
189*635a8641SAndroid Build Coastguard Worker // You just call AddWork() to add a delegate to the list of work to be done.
190*635a8641SAndroid Build Coastguard Worker // JoinAll() will make sure that all outstanding work is processed, and wait
191*635a8641SAndroid Build Coastguard Worker // for everything to finish.  You can reuse a pool, so you can call Start()
192*635a8641SAndroid Build Coastguard Worker // again after you've called JoinAll().
193*635a8641SAndroid Build Coastguard Worker class BASE_EXPORT DelegateSimpleThreadPool
194*635a8641SAndroid Build Coastguard Worker     : public DelegateSimpleThread::Delegate {
195*635a8641SAndroid Build Coastguard Worker  public:
196*635a8641SAndroid Build Coastguard Worker   typedef DelegateSimpleThread::Delegate Delegate;
197*635a8641SAndroid Build Coastguard Worker 
198*635a8641SAndroid Build Coastguard Worker   DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads);
199*635a8641SAndroid Build Coastguard Worker   ~DelegateSimpleThreadPool() override;
200*635a8641SAndroid Build Coastguard Worker 
201*635a8641SAndroid Build Coastguard Worker   // Start up all of the underlying threads, and start processing work if we
202*635a8641SAndroid Build Coastguard Worker   // have any.
203*635a8641SAndroid Build Coastguard Worker   void Start();
204*635a8641SAndroid Build Coastguard Worker 
205*635a8641SAndroid Build Coastguard Worker   // Make sure all outstanding work is finished, and wait for and destroy all
206*635a8641SAndroid Build Coastguard Worker   // of the underlying threads in the pool.
207*635a8641SAndroid Build Coastguard Worker   void JoinAll();
208*635a8641SAndroid Build Coastguard Worker 
209*635a8641SAndroid Build Coastguard Worker   // It is safe to AddWork() any time, before or after Start().
210*635a8641SAndroid Build Coastguard Worker   // Delegate* should always be a valid pointer, NULL is reserved internally.
211*635a8641SAndroid Build Coastguard Worker   void AddWork(Delegate* work, int repeat_count);
AddWork(Delegate * work)212*635a8641SAndroid Build Coastguard Worker   void AddWork(Delegate* work) {
213*635a8641SAndroid Build Coastguard Worker     AddWork(work, 1);
214*635a8641SAndroid Build Coastguard Worker   }
215*635a8641SAndroid Build Coastguard Worker 
216*635a8641SAndroid Build Coastguard Worker   // We implement the Delegate interface, for running our internal threads.
217*635a8641SAndroid Build Coastguard Worker   void Run() override;
218*635a8641SAndroid Build Coastguard Worker 
219*635a8641SAndroid Build Coastguard Worker  private:
220*635a8641SAndroid Build Coastguard Worker   const std::string name_prefix_;
221*635a8641SAndroid Build Coastguard Worker   int num_threads_;
222*635a8641SAndroid Build Coastguard Worker   std::vector<DelegateSimpleThread*> threads_;
223*635a8641SAndroid Build Coastguard Worker   base::queue<Delegate*> delegates_;
224*635a8641SAndroid Build Coastguard Worker   base::Lock lock_;            // Locks delegates_
225*635a8641SAndroid Build Coastguard Worker   WaitableEvent dry_;    // Not signaled when there is no work to do.
226*635a8641SAndroid Build Coastguard Worker 
227*635a8641SAndroid Build Coastguard Worker   DISALLOW_COPY_AND_ASSIGN(DelegateSimpleThreadPool);
228*635a8641SAndroid Build Coastguard Worker };
229*635a8641SAndroid Build Coastguard Worker 
230*635a8641SAndroid Build Coastguard Worker }  // namespace base
231*635a8641SAndroid Build Coastguard Worker 
232*635a8641SAndroid Build Coastguard Worker #endif  // BASE_THREADING_SIMPLE_THREAD_H_
233