base/thread.h

   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 #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
  13 namespace 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.
  20 class 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   };
  33
  34   // Constructor.
  35   // name is a display string to identify the thread.
  36   explicit Thread(const char *name);
  37
  38   // Destroys the thread, stopping it if necessary.
  39   //
  40   // NOTE: If you are subclassing from Thread, and you wish for your CleanUp
  41   // method to be called, then you need to call Stop() from your destructor.
  42   //
  43   virtual ~Thread();
  44
  45   // Starts the thread.  Returns true if the thread was successfully started;
  46   // otherwise, returns false.  Upon successful return, the message_loop()
  47   // getter will return non-null.
  48   //
  49   // Note: This function can't be called on Windows with the loader lock held;
  50   // i.e. during a DllMain, global object construction or destruction, atexit()
  51   // callback.
  52   bool Start();
  53
  54   // Starts the thread. Behaves exactly like Start in addition to allow to
  55   // override the default options.
  56   //
  57   // Note: This function can't be called on Windows with the loader lock held;
  58   // i.e. during a DllMain, global object construction or destruction, atexit()
  59   // callback.
  60   bool StartWithOptions(const Options& options);
  61
  62   // Signals the thread to exit and returns once the thread has exited.  After
  63   // this method returns, the Thread object is completely reset and may be used
  64   // as if it were newly constructed (i.e., Start may be called again).
  65   //
  66   // Stop may be called multiple times and is simply ignored if the thread is
  67   // already stopped.
  68   //
  69   // NOTE: This method is optional.  It is not strictly necessary to call this
  70   // method as the Thread's destructor will take care of stopping the thread if
  71   // necessary.
  72   //
  73   void Stop();
  74
  75   // Signals the thread to exit in the near future.
  76   //
  77   // WARNING: This function is not meant to be commonly used. Use at your own
  78   // risk. Calling this function will cause message_loop() to become invalid in
  79   // the near future. This function was created to workaround a specific
  80   // deadlock on Windows with printer worker thread. In any other case, Stop()
  81   // should be used.
  82   //
  83   // StopSoon should not be called multiple times as it is risky to do so. It
  84   // could cause a timing issue in message_loop() access. Call Stop() to reset
  85   // the thread object once it is known that the thread has quit.
  86   void StopSoon();
  87
  88   // Returns the message loop for this thread.  Use the MessageLoop's
  89   // PostTask methods to execute code on the thread.  This only returns
  90   // non-null after a successful call to Start.  After Stop has been called,
  91   // this will return NULL.
  92   //
  93   // NOTE: You must not call this MessageLoop's Quit method directly.  Use
  94   // the Thread's Stop method instead.
  95   //
  96   MessageLoop* message_loop() const { return message_loop_; }
  97
  98   // Set the name of this thread (for display in debugger too).
  99   const std::string &thread_name() { return name_; }
 100
 101   // The native thread handle.
 102   PlatformThreadHandle thread_handle() { return thread_; }
 103
 104  protected:
 105   // Called just prior to starting the message loop
 106   virtual void Init() {}
 107
 108   // Called just after the message loop ends
 109   virtual void CleanUp() {}
 110
 111   static void SetThreadWasQuitProperly(bool flag);
 112   static bool GetThreadWasQuitProperly();
 113
 114  private:
 115   // PlatformThread::Delegate methods:
 116   virtual void ThreadMain();
 117
 118   // We piggy-back on the startup_data_ member to know if we successfully
 119   // started the thread.  This way we know that we need to call Join.
 120   bool thread_was_started() const { return startup_data_ != NULL; }
 121
 122   // Used to pass data to ThreadMain.
 123   struct StartupData;
 124   StartupData* startup_data_;
 125
 126   // The thread's handle.
 127   PlatformThreadHandle thread_;
 128
 129   // The thread's message loop.  Valid only while the thread is alive.  Set
 130   // by the created thread.
 131   MessageLoop* message_loop_;
 132
 133   // Our thread's ID.  Used for debugging purposes.
 134   int thread_id_;
 135
 136   // The name of the thread.  Used for debugging purposes.
 137   std::string name_;
 138
 139   friend class ThreadQuitTask;
 140
 141   DISALLOW_COPY_AND_ASSIGN(Thread);
 142 };
 143
 144 }  // namespace base
 145
 146 #endif  // BASE_THREAD_H_
 147