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