Line data Source code
1 : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 : // Copyright (c) 2006-2009 The Chromium Authors. All rights reserved.
4 : // Use of this source code is governed by a BSD-style license that can be
5 : // found in the LICENSE file.
6 :
7 : #ifndef BASE_THREAD_H_
8 : #define BASE_THREAD_H_
9 :
10 : #include <stdint.h>
11 : #include <string>
12 :
13 : #include "base/message_loop.h"
14 : #include "base/platform_thread.h"
15 :
16 : namespace base {
17 :
18 : // A simple thread abstraction that establishes a MessageLoop on a new thread.
19 : // The consumer uses the MessageLoop of the thread to cause code to execute on
20 : // the thread. When this object is destroyed the thread is terminated. All
21 : // pending tasks queued on the thread's message loop will run to completion
22 : // before the thread is terminated.
23 : class Thread : PlatformThread::Delegate {
24 : public:
25 : struct Options {
26 : // Specifies the type of message loop that will be allocated on the thread.
27 : MessageLoop::Type message_loop_type;
28 :
29 : // Specifies the maximum stack size that the thread is allowed to use.
30 : // This does not necessarily correspond to the thread's initial stack size.
31 : // A value of 0 indicates that the default maximum should be used.
32 : size_t stack_size;
33 :
34 : // Specifies the transient and permanent hang timeouts for background hang
35 : // monitoring. A value of 0 indicates there is no timeout.
36 : uint32_t transient_hang_timeout;
37 : uint32_t permanent_hang_timeout;
38 :
39 6 : Options()
40 6 : : message_loop_type(MessageLoop::TYPE_DEFAULT)
41 : , stack_size(0)
42 : , transient_hang_timeout(0)
43 6 : , permanent_hang_timeout(0) {}
44 2 : Options(MessageLoop::Type type, size_t size)
45 2 : : message_loop_type(type)
46 : , stack_size(size)
47 : , transient_hang_timeout(0)
48 2 : , permanent_hang_timeout(0) {}
49 : };
50 :
51 : // Constructor.
52 : // name is a display string to identify the thread.
53 : explicit Thread(const char *name);
54 :
55 : // Destroys the thread, stopping it if necessary.
56 : //
57 : // NOTE: If you are subclassing from Thread, and you wish for your CleanUp
58 : // method to be called, then you need to call Stop() from your destructor.
59 : //
60 : virtual ~Thread();
61 :
62 : // Starts the thread. Returns true if the thread was successfully started;
63 : // otherwise, returns false. Upon successful return, the message_loop()
64 : // getter will return non-null.
65 : //
66 : // Note: This function can't be called on Windows with the loader lock held;
67 : // i.e. during a DllMain, global object construction or destruction, atexit()
68 : // callback.
69 : bool Start();
70 :
71 : // Starts the thread. Behaves exactly like Start in addition to allow to
72 : // override the default options.
73 : //
74 : // Note: This function can't be called on Windows with the loader lock held;
75 : // i.e. during a DllMain, global object construction or destruction, atexit()
76 : // callback.
77 : bool StartWithOptions(const Options& options);
78 :
79 : // Signals the thread to exit and returns once the thread has exited. After
80 : // this method returns, the Thread object is completely reset and may be used
81 : // as if it were newly constructed (i.e., Start may be called again).
82 : //
83 : // Stop may be called multiple times and is simply ignored if the thread is
84 : // already stopped.
85 : //
86 : // NOTE: This method is optional. It is not strictly necessary to call this
87 : // method as the Thread's destructor will take care of stopping the thread if
88 : // necessary.
89 : //
90 : void Stop();
91 :
92 : // Signals the thread to exit in the near future.
93 : //
94 : // WARNING: This function is not meant to be commonly used. Use at your own
95 : // risk. Calling this function will cause message_loop() to become invalid in
96 : // the near future. This function was created to workaround a specific
97 : // deadlock on Windows with printer worker thread. In any other case, Stop()
98 : // should be used.
99 : //
100 : // StopSoon should not be called multiple times as it is risky to do so. It
101 : // could cause a timing issue in message_loop() access. Call Stop() to reset
102 : // the thread object once it is known that the thread has quit.
103 : void StopSoon();
104 :
105 : // Returns the message loop for this thread. Use the MessageLoop's
106 : // PostTask methods to execute code on the thread. This only returns
107 : // non-null after a successful call to Start. After Stop has been called,
108 : // this will return NULL.
109 : //
110 : // NOTE: You must not call this MessageLoop's Quit method directly. Use
111 : // the Thread's Stop method instead.
112 : //
113 1671 : MessageLoop* message_loop() const { return message_loop_; }
114 :
115 : // Set the name of this thread (for display in debugger too).
116 : const std::string &thread_name() { return name_; }
117 :
118 : // The native thread handle.
119 : PlatformThreadHandle thread_handle() { return thread_; }
120 :
121 : // The thread ID.
122 10843 : PlatformThreadId thread_id() const { return thread_id_; }
123 :
124 : // Reset thread ID as current thread.
125 : PlatformThreadId reset_thread_id() {
126 : thread_id_ = PlatformThread::CurrentId();
127 : return thread_id_;
128 : }
129 :
130 : // Returns true if the thread has been started, and not yet stopped.
131 : // When a thread is running, the thread_id_ is non-zero.
132 35 : bool IsRunning() const { return thread_id_ != 0; }
133 :
134 : protected:
135 : // Called just prior to starting the message loop
136 5 : virtual void Init() {}
137 :
138 : // Called just after the message loop ends
139 0 : virtual void CleanUp() {}
140 :
141 : static void SetThreadWasQuitProperly(bool flag);
142 : static bool GetThreadWasQuitProperly();
143 :
144 : private:
145 : // PlatformThread::Delegate methods:
146 : virtual void ThreadMain();
147 :
148 : // We piggy-back on the startup_data_ member to know if we successfully
149 : // started the thread. This way we know that we need to call Join.
150 0 : bool thread_was_started() const { return startup_data_ != NULL; }
151 :
152 : // Used to pass data to ThreadMain.
153 : struct StartupData;
154 : StartupData* startup_data_;
155 :
156 : // The thread's handle.
157 : PlatformThreadHandle thread_;
158 :
159 : // The thread's message loop. Valid only while the thread is alive. Set
160 : // by the created thread.
161 : MessageLoop* message_loop_;
162 :
163 : // Our thread's ID.
164 : PlatformThreadId thread_id_;
165 :
166 : // The name of the thread. Used for debugging purposes.
167 : std::string name_;
168 :
169 : friend class ThreadQuitTask;
170 :
171 : DISALLOW_COPY_AND_ASSIGN(Thread);
172 : };
173 :
174 : } // namespace base
175 :
176 : #endif // BASE_THREAD_H_
|
