Port Android relocation packer to chromium build
[chromium-blink-merge.git] / base / threading / simple_thread.h
blobecd360405f1348bf899d05f61fca50a9fa0e0db0
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.
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.
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.
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.
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.
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.
40 #ifndef BASE_THREADING_SIMPLE_THREAD_H_
41 #define BASE_THREADING_SIMPLE_THREAD_H_
43 #include <string>
44 #include <queue>
45 #include <vector>
47 #include "base/base_export.h"
48 #include "base/basictypes.h"
49 #include "base/compiler_specific.h"
50 #include "base/threading/platform_thread.h"
51 #include "base/synchronization/lock.h"
52 #include "base/synchronization/waitable_event.h"
54 namespace base {
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.
58 class BASE_EXPORT SimpleThread : public PlatformThread::Delegate {
59 public:
60 class BASE_EXPORT Options {
61 public:
62 Options() : stack_size_(0) { }
63 ~Options() { }
65 // We use the standard compiler-supplied copy constructor.
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_;
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);
81 ~SimpleThread() override;
83 virtual void Start();
84 virtual void Join();
86 // Subclasses should override the Run method.
87 virtual void Run() = 0;
89 // Return the thread name prefix, or "unnamed" if none was supplied.
90 std::string name_prefix() { return name_prefix_; }
92 // Return the completed name including TID, only valid after Start().
93 std::string name() { return name_; }
95 // Return the thread id, only valid after Start().
96 PlatformThreadId tid() { return tid_; }
98 // Return True if Start() has ever been called.
99 bool HasBeenStarted();
101 // Return True if Join() has evern been called.
102 bool HasBeenJoined() { return joined_; }
104 // Overridden from PlatformThread::Delegate:
105 void ThreadMain() override;
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);
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.
123 class BASE_EXPORT DelegateSimpleThread : public SimpleThread {
124 public:
125 class BASE_EXPORT Delegate {
126 public:
127 Delegate() { }
128 virtual ~Delegate() { }
129 virtual void Run() = 0;
132 DelegateSimpleThread(Delegate* delegate,
133 const std::string& name_prefix);
134 DelegateSimpleThread(Delegate* delegate,
135 const std::string& name_prefix,
136 const Options& options);
138 ~DelegateSimpleThread() override;
139 void Run() override;
141 private:
142 Delegate* delegate_;
145 // DelegateSimpleThreadPool allows you to start up a fixed number of threads,
146 // and then add jobs which will be dispatched to the threads. This is
147 // convenient when you have a lot of small work that you want done
148 // multi-threaded, but don't want to spawn a thread for each small bit of work.
150 // You just call AddWork() to add a delegate to the list of work to be done.
151 // JoinAll() will make sure that all outstanding work is processed, and wait
152 // for everything to finish. You can reuse a pool, so you can call Start()
153 // again after you've called JoinAll().
154 class BASE_EXPORT DelegateSimpleThreadPool
155 : public DelegateSimpleThread::Delegate {
156 public:
157 typedef DelegateSimpleThread::Delegate Delegate;
159 DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads);
160 ~DelegateSimpleThreadPool() override;
162 // Start up all of the underlying threads, and start processing work if we
163 // have any.
164 void Start();
166 // Make sure all outstanding work is finished, and wait for and destroy all
167 // of the underlying threads in the pool.
168 void JoinAll();
170 // It is safe to AddWork() any time, before or after Start().
171 // Delegate* should always be a valid pointer, NULL is reserved internally.
172 void AddWork(Delegate* work, int repeat_count);
173 void AddWork(Delegate* work) {
174 AddWork(work, 1);
177 // We implement the Delegate interface, for running our internal threads.
178 void Run() override;
180 private:
181 const std::string name_prefix_;
182 int num_threads_;
183 std::vector<DelegateSimpleThread*> threads_;
184 std::queue<Delegate*> delegates_;
185 base::Lock lock_; // Locks delegates_
186 WaitableEvent dry_; // Not signaled when there is no work to do.
189 } // namespace base
191 #endif // BASE_THREADING_SIMPLE_THREAD_H_