simple_thread.h revision ddb351dbec246cf1fab5ec20d2d5520909041de1
1// Copyright (c) 2011 The Chromium 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// WARNING: You should probably be using Thread (thread.h) instead. Thread is 6// Chrome's message-loop based Thread abstraction, and if you are a 7// thread running in the browser, there will likely be assumptions 8// that your thread will have an associated message loop. 9// 10// This is a simple thread interface that backs to a native operating system 11// thread. You should use this only when you want a thread that does not have 12// an associated MessageLoop. Unittesting is the best example of this. 13// 14// The simplest interface to use is DelegateSimpleThread, which will create 15// a new thread, and execute the Delegate's virtual Run() in this new thread 16// until it has completed, exiting the thread. 17// 18// NOTE: You *MUST* call Join on the thread to clean up the underlying thread 19// resources. You are also responsible for destructing the SimpleThread object. 20// It is invalid to destroy a SimpleThread while it is running, or without 21// Start() having been called (and a thread never created). The Delegate 22// object should live as long as a DelegateSimpleThread. 23// 24// Thread Safety: A SimpleThread is not completely thread safe. It is safe to 25// access it from the creating thread or from the newly created thread. This 26// implies that the creator thread should be the thread that calls Join. 27// 28// Example: 29// class MyThreadRunner : public DelegateSimpleThread::Delegate { ... }; 30// MyThreadRunner runner; 31// DelegateSimpleThread thread(&runner, "good_name_here"); 32// thread.Start(); 33// // Start will return after the Thread has been successfully started and 34// // initialized. The newly created thread will invoke runner->Run(), and 35// // run until it returns. 36// thread.Join(); // Wait until the thread has exited. You *MUST* Join! 37// // The SimpleThread object is still valid, however you may not call Join 38// // or Start again. 39 40#ifndef BASE_THREADING_SIMPLE_THREAD_H_ 41#define BASE_THREADING_SIMPLE_THREAD_H_ 42#pragma once 43 44#include <string> 45#include <queue> 46#include <vector> 47 48#include "base/base_api.h" 49#include "base/basictypes.h" 50#include "base/threading/platform_thread.h" 51#include "base/synchronization/lock.h" 52#include "base/synchronization/waitable_event.h" 53 54namespace base { 55 56// This is the base SimpleThread. You can derive from it and implement the 57// virtual Run method, or you can use the DelegateSimpleThread interface. 58class BASE_API SimpleThread : public PlatformThread::Delegate { 59 public: 60 class BASE_API 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() { return event_.IsSignaled(); } 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(); 106 107 private: 108 const std::string name_prefix_; 109 std::string name_; 110 const Options options_; 111 PlatformThreadHandle thread_; // PlatformThread handle, invalid after Join! 112 WaitableEvent event_; // Signaled if Start() was ever called. 113 PlatformThreadId tid_; // The backing thread's id. 114 bool joined_; // True if Join has been called. 115}; 116 117class BASE_API DelegateSimpleThread : public SimpleThread { 118 public: 119 class BASE_API Delegate { 120 public: 121 Delegate() { } 122 virtual ~Delegate() { } 123 virtual void Run() = 0; 124 }; 125 126 DelegateSimpleThread(Delegate* delegate, 127 const std::string& name_prefix); 128 DelegateSimpleThread(Delegate* delegate, 129 const std::string& name_prefix, 130 const Options& options); 131 132 virtual ~DelegateSimpleThread(); 133 virtual void Run(); 134 private: 135 Delegate* delegate_; 136}; 137 138// DelegateSimpleThreadPool allows you to start up a fixed number of threads, 139// and then add jobs which will be dispatched to the threads. This is 140// convenient when you have a lot of small work that you want done 141// multi-threaded, but don't want to spawn a thread for each small bit of work. 142// 143// You just call AddWork() to add a delegate to the list of work to be done. 144// JoinAll() will make sure that all outstanding work is processed, and wait 145// for everything to finish. You can reuse a pool, so you can call Start() 146// again after you've called JoinAll(). 147class BASE_API DelegateSimpleThreadPool 148 : public DelegateSimpleThread::Delegate { 149 public: 150 typedef DelegateSimpleThread::Delegate Delegate; 151 152 DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads); 153 virtual ~DelegateSimpleThreadPool(); 154 155 // Start up all of the underlying threads, and start processing work if we 156 // have any. 157 void Start(); 158 159 // Make sure all outstanding work is finished, and wait for and destroy all 160 // of the underlying threads in the pool. 161 void JoinAll(); 162 163 // It is safe to AddWork() any time, before or after Start(). 164 // Delegate* should always be a valid pointer, NULL is reserved internally. 165 void AddWork(Delegate* work, int repeat_count); 166 void AddWork(Delegate* work) { 167 AddWork(work, 1); 168 } 169 170 // We implement the Delegate interface, for running our internal threads. 171 virtual void Run(); 172 173 private: 174 const std::string name_prefix_; 175 int num_threads_; 176 std::vector<DelegateSimpleThread*> threads_; 177 std::queue<Delegate*> delegates_; 178 base::Lock lock_; // Locks delegates_ 179 WaitableEvent dry_; // Not signaled when there is no work to do. 180}; 181 182} // namespace base 183 184#endif // BASE_THREADING_SIMPLE_THREAD_H_ 185