146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Copyright (c) 2011 The Chromium Authors. All rights reserved. 246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// found in the LICENSE file. 446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// WARNING: You should probably be using Thread (thread.h) instead. Thread is 646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Chrome's message-loop based Thread abstraction, and if you are a 746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// thread running in the browser, there will likely be assumptions 846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// that your thread will have an associated message loop. 946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// 1046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// This is a simple thread interface that backs to a native operating system 1146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// thread. You should use this only when you want a thread that does not have 1246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// an associated MessageLoop. Unittesting is the best example of this. 1346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// 1446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// The simplest interface to use is DelegateSimpleThread, which will create 1546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// a new thread, and execute the Delegate's virtual Run() in this new thread 1646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// until it has completed, exiting the thread. 1746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// 1846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// NOTE: You *MUST* call Join on the thread to clean up the underlying thread 1946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// resources. You are also responsible for destructing the SimpleThread object. 2046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// It is invalid to destroy a SimpleThread while it is running, or without 2146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Start() having been called (and a thread never created). The Delegate 2246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// object should live as long as a DelegateSimpleThread. 2346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// 2446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Thread Safety: A SimpleThread is not completely thread safe. It is safe to 2546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// access it from the creating thread or from the newly created thread. This 2646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// implies that the creator thread should be the thread that calls Join. 2746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// 2846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// Example: 2946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// class MyThreadRunner : public DelegateSimpleThread::Delegate { ... }; 3046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// MyThreadRunner runner; 3146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// DelegateSimpleThread thread(&runner, "good_name_here"); 3246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// thread.Start(); 3346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// // Start will return after the Thread has been successfully started and 3446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// // initialized. The newly created thread will invoke runner->Run(), and 3546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// // run until it returns. 3646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// thread.Join(); // Wait until the thread has exited. You *MUST* Join! 3746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// // The SimpleThread object is still valid, however you may not call Join 3846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// // or Start again. 3946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 4046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#ifndef BASE_THREADING_SIMPLE_THREAD_H_ 4146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#define BASE_THREADING_SIMPLE_THREAD_H_ 4246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 4346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include <string> 4446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include <queue> 4546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include <vector> 4646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 4746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/base_export.h" 4846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/basictypes.h" 4946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/compiler_specific.h" 5046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/threading/platform_thread.h" 5146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/synchronization/lock.h" 5246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "base/synchronization/waitable_event.h" 5346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 5446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)namespace base { 5546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 5646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// This is the base SimpleThread. You can derive from it and implement the 5746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)// virtual Run method, or you can use the DelegateSimpleThread interface. 58class BASE_EXPORT SimpleThread : public PlatformThread::Delegate { 59 public: 60 class BASE_EXPORT Options { 61 public: 62 Options() : stack_size_(0) { } 63 ~Options() { } 64 65 // We use the standard compiler-supplied copy constructor. 66 67 // A custom stack size, or 0 for the system default. 68 void set_stack_size(size_t size) { stack_size_ = size; } 69 size_t stack_size() const { return stack_size_; } 70 private: 71 size_t stack_size_; 72 }; 73 74 // Create a SimpleThread. |options| should be used to manage any specific 75 // configuration involving the thread creation and management. 76 // Every thread has a name, in the form of |name_prefix|/TID, for example 77 // "my_thread/321". The thread will not be created until Start() is called. 78 explicit SimpleThread(const std::string& name_prefix); 79 SimpleThread(const std::string& name_prefix, const Options& options); 80 81 virtual ~SimpleThread(); 82 83 virtual void Start(); 84 virtual void Join(); 85 86 // Subclasses should override the Run method. 87 virtual void Run() = 0; 88 89 // Return the thread name prefix, or "unnamed" if none was supplied. 90 std::string name_prefix() { return name_prefix_; } 91 92 // Return the completed name including TID, only valid after Start(). 93 std::string name() { return name_; } 94 95 // Return the thread id, only valid after Start(). 96 PlatformThreadId tid() { return tid_; } 97 98 // Return True if Start() has ever been called. 99 bool HasBeenStarted(); 100 101 // Return True if Join() has evern been called. 102 bool HasBeenJoined() { return joined_; } 103 104 // Overridden from PlatformThread::Delegate: 105 virtual void ThreadMain() OVERRIDE; 106 107 // Only set priorities with a careful understanding of the consequences. 108 // This is meant for very limited use cases. 109 void SetThreadPriority(ThreadPriority priority) { 110 PlatformThread::SetThreadPriority(thread_, priority); 111 } 112 113 private: 114 const std::string name_prefix_; 115 std::string name_; 116 const Options options_; 117 PlatformThreadHandle thread_; // PlatformThread handle, invalid after Join! 118 WaitableEvent event_; // Signaled if Start() was ever called. 119 PlatformThreadId tid_; // The backing thread's id. 120 bool joined_; // True if Join has been called. 121}; 122 123class BASE_EXPORT DelegateSimpleThread : public SimpleThread { 124 public: 125 class BASE_EXPORT Delegate { 126 public: 127 Delegate() { } 128 virtual ~Delegate() { } 129 virtual void Run() = 0; 130 }; 131 132 DelegateSimpleThread(Delegate* delegate, 133 const std::string& name_prefix); 134 DelegateSimpleThread(Delegate* delegate, 135 const std::string& name_prefix, 136 const Options& options); 137 138 virtual ~DelegateSimpleThread(); 139 virtual void Run() OVERRIDE; 140 private: 141 Delegate* delegate_; 142}; 143 144// DelegateSimpleThreadPool allows you to start up a fixed number of threads, 145// and then add jobs which will be dispatched to the threads. This is 146// convenient when you have a lot of small work that you want done 147// multi-threaded, but don't want to spawn a thread for each small bit of work. 148// 149// You just call AddWork() to add a delegate to the list of work to be done. 150// JoinAll() will make sure that all outstanding work is processed, and wait 151// for everything to finish. You can reuse a pool, so you can call Start() 152// again after you've called JoinAll(). 153class BASE_EXPORT DelegateSimpleThreadPool 154 : public DelegateSimpleThread::Delegate { 155 public: 156 typedef DelegateSimpleThread::Delegate Delegate; 157 158 DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads); 159 virtual ~DelegateSimpleThreadPool(); 160 161 // Start up all of the underlying threads, and start processing work if we 162 // have any. 163 void Start(); 164 165 // Make sure all outstanding work is finished, and wait for and destroy all 166 // of the underlying threads in the pool. 167 void JoinAll(); 168 169 // It is safe to AddWork() any time, before or after Start(). 170 // Delegate* should always be a valid pointer, NULL is reserved internally. 171 void AddWork(Delegate* work, int repeat_count); 172 void AddWork(Delegate* work) { 173 AddWork(work, 1); 174 } 175 176 // We implement the Delegate interface, for running our internal threads. 177 virtual void Run() OVERRIDE; 178 179 private: 180 const std::string name_prefix_; 181 int num_threads_; 182 std::vector<DelegateSimpleThread*> threads_; 183 std::queue<Delegate*> delegates_; 184 base::Lock lock_; // Locks delegates_ 185 WaitableEvent dry_; // Not signaled when there is no work to do. 186}; 187 188} // namespace base 189 190#endif // BASE_THREADING_SIMPLE_THREAD_H_ 191