13f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen// Copyright (c) 2011 The Chromium Authors. All rights reserved. 2c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Use of this source code is governed by a BSD-style license that can be 3c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// found in the LICENSE file. 4c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 5c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// WARNING: You should probably be using Thread (thread.h) instead. Thread is 6c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Chrome's message-loop based Thread abstraction, and if you are a 7c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// thread running in the browser, there will likely be assumptions 8c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// that your thread will have an associated message loop. 9c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 10c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// This is a simple thread interface that backs to a native operating system 11c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// thread. You should use this only when you want a thread that does not have 12c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// an associated MessageLoop. Unittesting is the best example of this. 13c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 14c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// The simplest interface to use is DelegateSimpleThread, which will create 15c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// a new thread, and execute the Delegate's virtual Run() in this new thread 16c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// until it has completed, exiting the thread. 17c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 18c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// NOTE: You *MUST* call Join on the thread to clean up the underlying thread 19c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// resources. You are also responsible for destructing the SimpleThread object. 20c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// It is invalid to destroy a SimpleThread while it is running, or without 21c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Start() having been called (and a thread never created). The Delegate 22c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// object should live as long as a DelegateSimpleThread. 23c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 24c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Thread Safety: A SimpleThread is not completely thread safe. It is safe to 25c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// access it from the creating thread or from the newly created thread. This 26c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// implies that the creator thread should be the thread that calls Join. 27c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 28c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// Example: 29c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// class MyThreadRunner : public DelegateSimpleThread::Delegate { ... }; 30c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// MyThreadRunner runner; 31c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// DelegateSimpleThread thread(&runner, "good_name_here"); 32c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// thread.Start(); 33c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// // Start will return after the Thread has been successfully started and 34c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// // initialized. The newly created thread will invoke runner->Run(), and 35c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// // run until it returns. 36c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// thread.Join(); // Wait until the thread has exited. You *MUST* Join! 37c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// // The SimpleThread object is still valid, however you may not call Join 38c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// // or Start again. 39c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 403f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen#ifndef BASE_THREADING_SIMPLE_THREAD_H_ 413f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen#define BASE_THREADING_SIMPLE_THREAD_H_ 423345a6884c488ff3a535c2c9acdd33d74b37e311Iain Merrick#pragma once 43c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 44c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include <string> 45c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include <queue> 46c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include <vector> 47c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 48ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsen#include "base/base_api.h" 49c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott#include "base/basictypes.h" 503f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen#include "base/threading/platform_thread.h" 5172a454cd3513ac24fbdd0e0cb9ad70b86a99b801Kristian Monsen#include "base/synchronization/lock.h" 523f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen#include "base/synchronization/waitable_event.h" 53c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 54c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scottnamespace base { 55c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 56c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// This is the base SimpleThread. You can derive from it and implement the 57c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// virtual Run method, or you can use the DelegateSimpleThread interface. 58ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsenclass BASE_API SimpleThread : public PlatformThread::Delegate { 59c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 60ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsen class BASE_API Options { 61c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 62c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott Options() : stack_size_(0) { } 63c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott ~Options() { } 64c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 65c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // We use the standard compiler-supplied copy constructor. 66c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 67c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // A custom stack size, or 0 for the system default. 68c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott void set_stack_size(size_t size) { stack_size_ = size; } 69c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott size_t stack_size() const { return stack_size_; } 70c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott private: 71c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott size_t stack_size_; 72c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott }; 73c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 74c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Create a SimpleThread. |options| should be used to manage any specific 75c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // configuration involving the thread creation and management. 76c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Every thread has a name, in the form of |name_prefix|/TID, for example 77c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // "my_thread/321". The thread will not be created until Start() is called. 78731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick explicit SimpleThread(const std::string& name_prefix); 79731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick SimpleThread(const std::string& name_prefix, const Options& options); 80c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 81c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual ~SimpleThread(); 82c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 83c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Start(); 84c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Join(); 85c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 86c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Subclasses should override the Run method. 87c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Run() = 0; 88c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 89c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return the thread name prefix, or "unnamed" if none was supplied. 90c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::string name_prefix() { return name_prefix_; } 91c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 92c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return the completed name including TID, only valid after Start(). 93c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::string name() { return name_; } 94c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 95c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return the thread id, only valid after Start(). 96c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott PlatformThreadId tid() { return tid_; } 97c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 98c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return True if Start() has ever been called. 99c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott bool HasBeenStarted() { return event_.IsSignaled(); } 100c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 101c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Return True if Join() has evern been called. 102c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott bool HasBeenJoined() { return joined_; } 103c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 1043f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen // Overridden from PlatformThread::Delegate: 1053f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen virtual void ThreadMain(); 1063f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen 107c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott private: 108c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott const std::string name_prefix_; 109c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::string name_; 110c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott const Options options_; 111c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott PlatformThreadHandle thread_; // PlatformThread handle, invalid after Join! 112c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott WaitableEvent event_; // Signaled if Start() was ever called. 113c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott PlatformThreadId tid_; // The backing thread's id. 114c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott bool joined_; // True if Join has been called. 115c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott}; 116c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 117ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsenclass BASE_API DelegateSimpleThread : public SimpleThread { 118c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 119ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsen class BASE_API Delegate { 120c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 121c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott Delegate() { } 122c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual ~Delegate() { } 123c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Run() = 0; 124c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott }; 125c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 126c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott DelegateSimpleThread(Delegate* delegate, 127731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick const std::string& name_prefix); 128c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott DelegateSimpleThread(Delegate* delegate, 129c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott const std::string& name_prefix, 130731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick const Options& options); 131c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 132731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick virtual ~DelegateSimpleThread(); 133c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Run(); 134c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott private: 135c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott Delegate* delegate_; 136c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott}; 137c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 138c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// DelegateSimpleThreadPool allows you to start up a fixed number of threads, 139c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// and then add jobs which will be dispatched to the threads. This is 140c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// convenient when you have a lot of small work that you want done 141c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// multi-threaded, but don't want to spawn a thread for each small bit of work. 142c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// 143c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// You just call AddWork() to add a delegate to the list of work to be done. 144c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// JoinAll() will make sure that all outstanding work is processed, and wait 145c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// for everything to finish. You can reuse a pool, so you can call Start() 146c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott// again after you've called JoinAll(). 147ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsenclass BASE_API DelegateSimpleThreadPool 148ddb351dbec246cf1fab5ec20d2d5520909041de1Kristian Monsen : public DelegateSimpleThread::Delegate { 149c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott public: 150c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott typedef DelegateSimpleThread::Delegate Delegate; 151c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 152731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads); 153731df977c0511bca2206b5f333555b1205ff1f43Iain Merrick virtual ~DelegateSimpleThreadPool(); 154c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 155c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Start up all of the underlying threads, and start processing work if we 156c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // have any. 157c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott void Start(); 158c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 159c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Make sure all outstanding work is finished, and wait for and destroy all 160c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // of the underlying threads in the pool. 161c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott void JoinAll(); 162c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 163c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // It is safe to AddWork() any time, before or after Start(). 164c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // Delegate* should always be a valid pointer, NULL is reserved internally. 165c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott void AddWork(Delegate* work, int repeat_count); 166c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott void AddWork(Delegate* work) { 167c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott AddWork(work, 1); 168c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott } 169c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 170c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott // We implement the Delegate interface, for running our internal threads. 171c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott virtual void Run(); 172c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 173c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott private: 174c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott const std::string name_prefix_; 175c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott int num_threads_; 176c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::vector<DelegateSimpleThread*> threads_; 177c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott std::queue<Delegate*> delegates_; 17872a454cd3513ac24fbdd0e0cb9ad70b86a99b801Kristian Monsen base::Lock lock_; // Locks delegates_ 179c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott WaitableEvent dry_; // Not signaled when there is no work to do. 180c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott}; 181c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 182c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott} // namespace base 183c7f5f8508d98d5952d42ed7648c2a8f30a4da156Patrick Scott 1843f50c38dc070f4bb515c1b64450dae14f316474eKristian Monsen#endif // BASE_THREADING_SIMPLE_THREAD_H_ 185