1 // Copyright (c) 2006-2009 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.
10 #include "base/message_loop.h"
11 #include "base/platform_thread.h"
15 // A simple thread abstraction that establishes a MessageLoop on a new thread.
16 // The consumer uses the MessageLoop of the thread to cause code to execute on
17 // the thread. When this object is destroyed the thread is terminated. All
18 // pending tasks queued on the thread's message loop will run to completion
19 // before the thread is terminated.
20 class Thread
: PlatformThread::Delegate
{
23 // Specifies the type of message loop that will be allocated on the thread.
24 MessageLoop::Type message_loop_type
;
26 // Specifies the maximum stack size that the thread is allowed to use.
27 // This does not necessarily correspond to the thread's initial stack size.
28 // A value of 0 indicates that the default maximum should be used.
31 Options() : message_loop_type(MessageLoop::TYPE_DEFAULT
), stack_size(0) {}
32 Options(MessageLoop::Type type
, size_t size
)
33 : message_loop_type(type
), stack_size(size
) {}
37 // name is a display string to identify the thread.
38 explicit Thread(const char *name
);
40 // Destroys the thread, stopping it if necessary.
42 // NOTE: If you are subclassing from Thread, and you wish for your CleanUp
43 // method to be called, then you need to call Stop() from your destructor.
47 // Starts the thread. Returns true if the thread was successfully started;
48 // otherwise, returns false. Upon successful return, the message_loop()
49 // getter will return non-null.
51 // Note: This function can't be called on Windows with the loader lock held;
52 // i.e. during a DllMain, global object construction or destruction, atexit()
56 // Starts the thread. Behaves exactly like Start in addition to allow to
57 // override the default options.
59 // Note: This function can't be called on Windows with the loader lock held;
60 // i.e. during a DllMain, global object construction or destruction, atexit()
62 bool StartWithOptions(const Options
& options
);
64 // Signals the thread to exit and returns once the thread has exited. After
65 // this method returns, the Thread object is completely reset and may be used
66 // as if it were newly constructed (i.e., Start may be called again).
68 // Stop may be called multiple times and is simply ignored if the thread is
71 // NOTE: This method is optional. It is not strictly necessary to call this
72 // method as the Thread's destructor will take care of stopping the thread if
77 // Signals the thread to exit in the near future.
79 // WARNING: This function is not meant to be commonly used. Use at your own
80 // risk. Calling this function will cause message_loop() to become invalid in
81 // the near future. This function was created to workaround a specific
82 // deadlock on Windows with printer worker thread. In any other case, Stop()
85 // StopSoon should not be called multiple times as it is risky to do so. It
86 // could cause a timing issue in message_loop() access. Call Stop() to reset
87 // the thread object once it is known that the thread has quit.
90 // Returns the message loop for this thread. Use the MessageLoop's
91 // PostTask methods to execute code on the thread. This only returns
92 // non-null after a successful call to Start. After Stop has been called,
93 // this will return NULL.
95 // NOTE: You must not call this MessageLoop's Quit method directly. Use
96 // the Thread's Stop method instead.
98 MessageLoop
* message_loop() const { return message_loop_
; }
100 // Set the name of this thread (for display in debugger too).
101 const std::string
&thread_name() { return name_
; }
103 // The native thread handle.
104 PlatformThreadHandle
thread_handle() { return thread_
; }
107 PlatformThreadId
thread_id() const { return thread_id_
; }
109 // Returns true if the thread has been started, and not yet stopped.
110 // When a thread is running, the thread_id_ is non-zero.
111 bool IsRunning() const { return thread_id_
!= 0; }
114 // Called just prior to starting the message loop
115 virtual void Init() {}
117 // Called to start the message loop
118 virtual void Run(MessageLoop
* message_loop
);
120 // Called just after the message loop ends
121 virtual void CleanUp() {}
123 static void SetThreadWasQuitProperly(bool flag
);
124 static bool GetThreadWasQuitProperly();
126 void set_message_loop(MessageLoop
* message_loop
) {
127 message_loop_
= message_loop
;
131 // PlatformThread::Delegate methods:
132 virtual void ThreadMain();
134 // We piggy-back on the startup_data_ member to know if we successfully
135 // started the thread. This way we know that we need to call Join.
136 bool thread_was_started() const { return startup_data_
!= NULL
; }
138 // If true, we're in the middle of stopping, and shouldn't access
139 // |message_loop_|. It may non-NULL and invalid.
142 // Used to pass data to ThreadMain.
144 StartupData
* startup_data_
;
146 // The thread's handle.
147 PlatformThreadHandle thread_
;
149 // The thread's message loop. Valid only while the thread is alive. Set
150 // by the created thread.
151 MessageLoop
* message_loop_
;
154 PlatformThreadId thread_id_
;
156 // The name of the thread. Used for debugging purposes.
159 friend class ThreadQuitTask
;
161 DISALLOW_COPY_AND_ASSIGN(Thread
);
166 #endif // BASE_THREAD_H_