src/base/threading/simple_thread.h

   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.
   4
   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.
  13 //
  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.
  17 //
  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.
  23 //
  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.
  27 //
  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.
  39
  40 #ifndef BASE_THREADING_SIMPLE_THREAD_H_
  41 #define BASE_THREADING_SIMPLE_THREAD_H_
  42
  43 #include <string>
  44 #include <queue>
  45 #include <vector>
  46
  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"
  53
  54 namespace base {
  55
  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() { }
  64
  65     // We use the standard compiler-supplied copy constructor.
  66
  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_;
  72   };
  73
  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);
  80
  81   virtual ~SimpleThread();
  82
  83   virtual void Start();
  84   virtual void Join();
  85
  86   // Subclasses should override the Run method.
  87   virtual void Run() = 0;
  88
  89   // Return the thread name prefix, or "unnamed" if none was supplied.
  90   std::string name_prefix() { return name_prefix_; }
  91
  92   // Return the completed name including TID, only valid after Start().
  93   std::string name() { return name_; }
  94
  95   // Return the thread id, only valid after Start().
  96   PlatformThreadId tid() { return tid_; }
  97
  98   // Return True if Start() has ever been called.
  99   bool HasBeenStarted();
 100
 101   // Return True if Join() has evern been called.
 102   bool HasBeenJoined() { return joined_; }
 103
 104   // Overridden from PlatformThread::Delegate:
 105   virtual void ThreadMain() OVERRIDE;
 106
 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);
 111   }
 112
 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.
 121 };
 122
 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;
 130   };
 131
 132   DelegateSimpleThread(Delegate* delegate,
 133                        const std::string& name_prefix);
 134   DelegateSimpleThread(Delegate* delegate,
 135                        const std::string& name_prefix,
 136                        const Options& options);
 137
 138   virtual ~DelegateSimpleThread();
 139   virtual void Run() OVERRIDE;
 140  private:
 141   Delegate* delegate_;
 142 };
 143
 144 // DelegateSimpleThreadPool allows you to start up a fixed number of threads,
 145 // and then add jobs which will be dispatched to the threads.  This is
 146 // convenient when you have a lot of small work that you want done
 147 // multi-threaded, but don't want to spawn a thread for each small bit of work.
 148 //
 149 // You just call AddWork() to add a delegate to the list of work to be done.
 150 // JoinAll() will make sure that all outstanding work is processed, and wait
 151 // for everything to finish.  You can reuse a pool, so you can call Start()
 152 // again after you've called JoinAll().
 153 class BASE_EXPORT DelegateSimpleThreadPool
 154     : public DelegateSimpleThread::Delegate {
 155  public:
 156   typedef DelegateSimpleThread::Delegate Delegate;
 157
 158   DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads);
 159   virtual ~DelegateSimpleThreadPool();
 160
 161   // Start up all of the underlying threads, and start processing work if we
 162   // have any.
 163   void Start();
 164
 165   // Make sure all outstanding work is finished, and wait for and destroy all
 166   // of the underlying threads in the pool.
 167   void JoinAll();
 168
 169   // It is safe to AddWork() any time, before or after Start().
 170   // Delegate* should always be a valid pointer, NULL is reserved internally.
 171   void AddWork(Delegate* work, int repeat_count);
 172   void AddWork(Delegate* work) {
 173     AddWork(work, 1);
 174   }
 175
 176   // We implement the Delegate interface, for running our internal threads.
 177   virtual void Run() OVERRIDE;
 178
 179  private:
 180   const std::string name_prefix_;
 181   int num_threads_;
 182   std::vector<DelegateSimpleThread*> threads_;
 183   std::queue<Delegate*> delegates_;
 184   base::Lock lock_;            // Locks delegates_
 185   WaitableEvent dry_;    // Not signaled when there is no work to do.
 186 };
 187
 188 }  // namespace base
 189
 190 #endif  // BASE_THREADING_SIMPLE_THREAD_H_