1 : // Copyright (c) 2006-2008 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_SIMPLE_THREAD_H_
41 : #define BASE_SIMPLE_THREAD_H_
42 :
43 : #include <string>
44 : #include <queue>
45 : #include <vector>
46 :
47 : #include "base/basictypes.h"
48 : #include "base/lock.h"
49 : #include "base/waitable_event.h"
50 : #include "base/platform_thread.h"
51 :
52 : namespace base {
53 :
54 : // This is the base SimpleThread. You can derive from it and implement the
55 : // virtual Run method, or you can use the DelegateSimpleThread interface.
56 : class SimpleThread : public PlatformThread::Delegate {
57 : public:
58 : class Options {
59 : public:
60 0 : Options() : stack_size_(0) { }
61 0 : ~Options() { }
62 :
63 : // We use the standard compiler-supplied copy constructor.
64 :
65 : // A custom stack size, or 0 for the system default.
66 : void set_stack_size(size_t size) { stack_size_ = size; }
67 0 : size_t stack_size() const { return stack_size_; }
68 : private:
69 : size_t stack_size_;
70 : };
71 :
72 : // Create a SimpleThread. |options| should be used to manage any specific
73 : // configuration involving the thread creation and management.
74 : // Every thread has a name, in the form of |name_prefix|/TID, for example
75 : // "my_thread/321". The thread will not be created until Start() is called.
76 0 : explicit SimpleThread(const std::string& name_prefix)
77 : : name_prefix_(name_prefix), name_(name_prefix),
78 0 : thread_(), event_(true, false), tid_(0), joined_(false) { }
79 : SimpleThread(const std::string& name_prefix, const Options& options)
80 : : name_prefix_(name_prefix), name_(name_prefix), options_(options),
81 : thread_(), event_(true, false), tid_(0), joined_(false) { }
82 :
83 : virtual ~SimpleThread();
84 :
85 : virtual void Start();
86 : virtual void Join();
87 :
88 : // We follow the PlatformThread Delegate interface.
89 : virtual void ThreadMain();
90 :
91 : // Subclasses should override the Run method.
92 : virtual void Run() = 0;
93 :
94 : // Return the thread name prefix, or "unnamed" if none was supplied.
95 : std::string name_prefix() { return name_prefix_; }
96 :
97 : // Return the completed name including TID, only valid after Start().
98 : std::string name() { return name_; }
99 :
100 : // Return the thread id, only valid after Start().
101 : PlatformThreadId tid() { return tid_; }
102 :
103 : // Return True if Start() has ever been called.
104 0 : bool HasBeenStarted() { return event_.IsSignaled(); }
105 :
106 : // Return True if Join() has evern been called.
107 0 : bool HasBeenJoined() { return joined_; }
108 :
109 : private:
110 : const std::string name_prefix_;
111 : std::string name_;
112 : const Options options_;
113 : PlatformThreadHandle thread_; // PlatformThread handle, invalid after Join!
114 : WaitableEvent event_; // Signaled if Start() was ever called.
115 : PlatformThreadId tid_; // The backing thread's id.
116 : bool joined_; // True if Join has been called.
117 : };
118 :
119 : class DelegateSimpleThread : public SimpleThread {
120 : public:
121 : class Delegate {
122 : public:
123 : Delegate() { }
124 0 : virtual ~Delegate() { }
125 : virtual void Run() = 0;
126 : };
127 :
128 0 : DelegateSimpleThread(Delegate* delegate,
129 : const std::string& name_prefix)
130 0 : : SimpleThread(name_prefix), delegate_(delegate) { }
131 : DelegateSimpleThread(Delegate* delegate,
132 : const std::string& name_prefix,
133 : const Options& options)
134 : : SimpleThread(name_prefix, options), delegate_(delegate) { }
135 :
136 0 : virtual ~DelegateSimpleThread() { }
137 : virtual void Run();
138 : private:
139 : Delegate* delegate_;
140 : };
141 :
142 : // DelegateSimpleThreadPool allows you to start up a fixed number of threads,
143 : // and then add jobs which will be dispatched to the threads. This is
144 : // convenient when you have a lot of small work that you want done
145 : // multi-threaded, but don't want to spawn a thread for each small bit of work.
146 : //
147 : // You just call AddWork() to add a delegate to the list of work to be done.
148 : // JoinAll() will make sure that all outstanding work is processed, and wait
149 : // for everything to finish. You can reuse a pool, so you can call Start()
150 : // again after you've called JoinAll().
151 : class DelegateSimpleThreadPool : public DelegateSimpleThread::Delegate {
152 : public:
153 : typedef DelegateSimpleThread::Delegate Delegate;
154 :
155 : DelegateSimpleThreadPool(const std::string name_prefix, int num_threads)
156 : : name_prefix_(name_prefix), num_threads_(num_threads),
157 : dry_(true, false) { }
158 : ~DelegateSimpleThreadPool();
159 :
160 : // Start up all of the underlying threads, and start processing work if we
161 : // have any.
162 : void Start();
163 :
164 : // Make sure all outstanding work is finished, and wait for and destroy all
165 : // of the underlying threads in the pool.
166 : void JoinAll();
167 :
168 : // It is safe to AddWork() any time, before or after Start().
169 : // Delegate* should always be a valid pointer, NULL is reserved internally.
170 : void AddWork(Delegate* work, int repeat_count);
171 : void AddWork(Delegate* work) {
172 : AddWork(work, 1);
173 : }
174 :
175 : // We implement the Delegate interface, for running our internal threads.
176 : virtual void Run();
177 :
178 : private:
179 : const std::string name_prefix_;
180 : int num_threads_;
181 : std::vector<DelegateSimpleThread*> threads_;
182 : std::queue<Delegate*> delegates_;
183 : Lock lock_; // Locks delegates_
184 : WaitableEvent dry_; // Not signaled when there is no work to do.
185 : };
186 :
187 : } // namespace base
188 :
189 : #endif // BASE_SIMPLE_THREAD_H_
|