michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // WARNING: You should probably be using Thread (thread.h) instead.  Thread is
michael@0: //          Chrome's message-loop based Thread abstraction, and if you are a
michael@0: //          thread running in the browser, there will likely be assumptions
michael@0: //          that your thread will have an associated message loop.
michael@0: //
michael@0: // This is a simple thread interface that backs to a native operating system
michael@0: // thread.  You should use this only when you want a thread that does not have
michael@0: // an associated MessageLoop.  Unittesting is the best example of this.
michael@0: //
michael@0: // The simplest interface to use is DelegateSimpleThread, which will create
michael@0: // a new thread, and execute the Delegate's virtual Run() in this new thread
michael@0: // until it has completed, exiting the thread.
michael@0: //
michael@0: // NOTE: You *MUST* call Join on the thread to clean up the underlying thread
michael@0: // resources.  You are also responsible for destructing the SimpleThread object.
michael@0: // It is invalid to destroy a SimpleThread while it is running, or without
michael@0: // Start() having been called (and a thread never created).  The Delegate
michael@0: // object should live as long as a DelegateSimpleThread.
michael@0: //
michael@0: // Thread Safety: A SimpleThread is not completely thread safe.  It is safe to
michael@0: // access it from the creating thread or from the newly created thread.  This
michael@0: // implies that the creator thread should be the thread that calls Join.
michael@0: //
michael@0: // Example:
michael@0: //   class MyThreadRunner : public DelegateSimpleThread::Delegate { ... };
michael@0: //   MyThreadRunner runner;
michael@0: //   DelegateSimpleThread thread(&runner, "good_name_here");
michael@0: //   thread.Start();
michael@0: //   // Start will return after the Thread has been successfully started and
michael@0: //   // initialized.  The newly created thread will invoke runner->Run(), and
michael@0: //   // run until it returns.
michael@0: //   thread.Join();  // Wait until the thread has exited.  You *MUST* Join!
michael@0: //   // The SimpleThread object is still valid, however you may not call Join
michael@0: //   // or Start again.
michael@0: 
michael@0: #ifndef BASE_SIMPLE_THREAD_H_
michael@0: #define BASE_SIMPLE_THREAD_H_
michael@0: 
michael@0: #include <string>
michael@0: #include <queue>
michael@0: #include <vector>
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: #include "base/lock.h"
michael@0: #include "base/waitable_event.h"
michael@0: #include "base/platform_thread.h"
michael@0: 
michael@0: namespace base {
michael@0: 
michael@0: // This is the base SimpleThread.  You can derive from it and implement the
michael@0: // virtual Run method, or you can use the DelegateSimpleThread interface.
michael@0: class SimpleThread : public PlatformThread::Delegate {
michael@0:  public:
michael@0:   class Options {
michael@0:    public:
michael@0:     Options() : stack_size_(0) { }
michael@0:     ~Options() { }
michael@0: 
michael@0:     // We use the standard compiler-supplied copy constructor.
michael@0: 
michael@0:     // A custom stack size, or 0 for the system default.
michael@0:     void set_stack_size(size_t size) { stack_size_ = size; }
michael@0:     size_t stack_size() const { return stack_size_; }
michael@0:    private:
michael@0:     size_t stack_size_;
michael@0:   };
michael@0: 
michael@0:   // Create a SimpleThread.  |options| should be used to manage any specific
michael@0:   // configuration involving the thread creation and management.
michael@0:   // Every thread has a name, in the form of |name_prefix|/TID, for example
michael@0:   // "my_thread/321".  The thread will not be created until Start() is called.
michael@0:   explicit SimpleThread(const std::string& name_prefix)
michael@0:       : name_prefix_(name_prefix), name_(name_prefix),
michael@0:         thread_(), event_(true, false), tid_(0), joined_(false) { }
michael@0:   SimpleThread(const std::string& name_prefix, const Options& options)
michael@0:       : name_prefix_(name_prefix), name_(name_prefix), options_(options),
michael@0:         thread_(), event_(true, false), tid_(0), joined_(false) { }
michael@0: 
michael@0:   virtual ~SimpleThread();
michael@0: 
michael@0:   virtual void Start();
michael@0:   virtual void Join();
michael@0: 
michael@0:   // We follow the PlatformThread Delegate interface.
michael@0:   virtual void ThreadMain();
michael@0: 
michael@0:   // Subclasses should override the Run method.
michael@0:   virtual void Run() = 0;
michael@0: 
michael@0:   // Return the thread name prefix, or "unnamed" if none was supplied.
michael@0:   std::string name_prefix() { return name_prefix_; }
michael@0: 
michael@0:   // Return the completed name including TID, only valid after Start().
michael@0:   std::string name() { return name_; }
michael@0: 
michael@0:   // Return the thread id, only valid after Start().
michael@0:   PlatformThreadId tid() { return tid_; }
michael@0: 
michael@0:   // Return True if Start() has ever been called.
michael@0:   bool HasBeenStarted() { return event_.IsSignaled(); }
michael@0: 
michael@0:   // Return True if Join() has evern been called.
michael@0:   bool HasBeenJoined() { return joined_; }
michael@0: 
michael@0:  private:
michael@0:   const std::string name_prefix_;
michael@0:   std::string name_;
michael@0:   const Options options_;
michael@0:   PlatformThreadHandle thread_;  // PlatformThread handle, invalid after Join!
michael@0:   WaitableEvent event_;          // Signaled if Start() was ever called.
michael@0:   PlatformThreadId tid_;         // The backing thread's id.
michael@0:   bool joined_;                  // True if Join has been called.
michael@0: };
michael@0: 
michael@0: class DelegateSimpleThread : public SimpleThread {
michael@0:  public:
michael@0:   class Delegate {
michael@0:    public:
michael@0:     Delegate() { }
michael@0:     virtual ~Delegate() { }
michael@0:     virtual void Run() = 0;
michael@0:   };
michael@0: 
michael@0:   DelegateSimpleThread(Delegate* delegate,
michael@0:                        const std::string& name_prefix)
michael@0:       : SimpleThread(name_prefix), delegate_(delegate) { }
michael@0:   DelegateSimpleThread(Delegate* delegate,
michael@0:                        const std::string& name_prefix,
michael@0:                        const Options& options)
michael@0:       : SimpleThread(name_prefix, options), delegate_(delegate) { }
michael@0: 
michael@0:   virtual ~DelegateSimpleThread() { }
michael@0:   virtual void Run();
michael@0:  private:
michael@0:   Delegate* delegate_;
michael@0: };
michael@0: 
michael@0: // DelegateSimpleThreadPool allows you to start up a fixed number of threads,
michael@0: // and then add jobs which will be dispatched to the threads.  This is
michael@0: // convenient when you have a lot of small work that you want done
michael@0: // multi-threaded, but don't want to spawn a thread for each small bit of work.
michael@0: //
michael@0: // You just call AddWork() to add a delegate to the list of work to be done.
michael@0: // JoinAll() will make sure that all outstanding work is processed, and wait
michael@0: // for everything to finish.  You can reuse a pool, so you can call Start()
michael@0: // again after you've called JoinAll().
michael@0: class DelegateSimpleThreadPool : public DelegateSimpleThread::Delegate {
michael@0:  public:
michael@0:   typedef DelegateSimpleThread::Delegate Delegate;
michael@0: 
michael@0:   DelegateSimpleThreadPool(const std::string name_prefix, int num_threads)
michael@0:       : name_prefix_(name_prefix), num_threads_(num_threads),
michael@0:         dry_(true, false) { }
michael@0:   ~DelegateSimpleThreadPool();
michael@0: 
michael@0:   // Start up all of the underlying threads, and start processing work if we
michael@0:   // have any.
michael@0:   void Start();
michael@0: 
michael@0:   // Make sure all outstanding work is finished, and wait for and destroy all
michael@0:   // of the underlying threads in the pool.
michael@0:   void JoinAll();
michael@0: 
michael@0:   // It is safe to AddWork() any time, before or after Start().
michael@0:   // Delegate* should always be a valid pointer, NULL is reserved internally.
michael@0:   void AddWork(Delegate* work, int repeat_count);
michael@0:   void AddWork(Delegate* work) {
michael@0:     AddWork(work, 1);
michael@0:   }
michael@0: 
michael@0:   // We implement the Delegate interface, for running our internal threads.
michael@0:   virtual void Run();
michael@0: 
michael@0:  private:
michael@0:   const std::string name_prefix_;
michael@0:   int num_threads_;
michael@0:   std::vector<DelegateSimpleThread*> threads_;
michael@0:   std::queue<Delegate*> delegates_;
michael@0:   Lock lock_;            // Locks delegates_
michael@0:   WaitableEvent dry_;    // Not signaled when there is no work to do.
michael@0: };
michael@0: 
michael@0: }  // namespace base
michael@0: 
michael@0: #endif  // BASE_SIMPLE_THREAD_H_