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.
4
5#ifndef BASE_THREAD_H_
6#define BASE_THREAD_H_
7
8#include <string>
9
10#include "base/message_loop.h"
11#include "base/platform_thread.h"
12
13namespace base {
14
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.
20class Thread : PlatformThread::Delegate {
21 public:
22  struct Options {
23    // Specifies the type of message loop that will be allocated on the thread.
24    MessageLoop::Type message_loop_type;
25
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.
29    size_t stack_size;
30
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) {}
34  };
35
36  // Constructor.
37  // name is a display string to identify the thread.
38  explicit Thread(const char *name);
39
40  // Destroys the thread, stopping it if necessary.
41  //
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.
44  //
45  virtual ~Thread();
46
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.
50  //
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()
53  // callback.
54  bool Start();
55
56  // Starts the thread. Behaves exactly like Start in addition to allow to
57  // override the default options.
58  //
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()
61  // callback.
62  bool StartWithOptions(const Options& options);
63
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).
67  //
68  // Stop may be called multiple times and is simply ignored if the thread is
69  // already stopped.
70  //
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
73  // necessary.
74  //
75  void Stop();
76
77  // Signals the thread to exit in the near future.
78  //
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()
83  // should be used.
84  //
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.
88  void StopSoon();
89
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.
94  //
95  // NOTE: You must not call this MessageLoop's Quit method directly.  Use
96  // the Thread's Stop method instead.
97  //
98  MessageLoop* message_loop() const { return message_loop_; }
99
100  // Set the name of this thread (for display in debugger too).
101  const std::string &thread_name() { return name_; }
102
103  // The native thread handle.
104  PlatformThreadHandle thread_handle() { return thread_; }
105
106  // The thread ID.
107  PlatformThreadId thread_id() const { return thread_id_; }
108
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; }
112
113 protected:
114  // Called just prior to starting the message loop
115  virtual void Init() {}
116
117  // Called to start the message loop
118  virtual void Run(MessageLoop* message_loop);
119
120  // Called just after the message loop ends
121  virtual void CleanUp() {}
122
123  static void SetThreadWasQuitProperly(bool flag);
124  static bool GetThreadWasQuitProperly();
125
126  void set_message_loop(MessageLoop* message_loop) {
127    message_loop_ = message_loop;
128  }
129
130 private:
131  // PlatformThread::Delegate methods:
132  virtual void ThreadMain();
133
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; }
137
138  // If true, we're in the middle of stopping, and shouldn't access
139  // |message_loop_|. It may non-NULL and invalid.
140  bool stopping_;
141
142  // Used to pass data to ThreadMain.
143  struct StartupData;
144  StartupData* startup_data_;
145
146  // The thread's handle.
147  PlatformThreadHandle thread_;
148
149  // The thread's message loop.  Valid only while the thread is alive.  Set
150  // by the created thread.
151  MessageLoop* message_loop_;
152
153  // Our thread's ID.
154  PlatformThreadId thread_id_;
155
156  // The name of the thread.  Used for debugging purposes.
157  std::string name_;
158
159  friend class ThreadQuitTask;
160
161  DISALLOW_COPY_AND_ASSIGN(Thread);
162};
163
164}  // namespace base
165
166#endif  // BASE_THREAD_H_
167