15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2011 The Chromium Authors. All rights reserved.
25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be
35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file.
45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// WARNING: You should probably be using Thread (thread.h) instead.  Thread is
65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//          Chrome's message-loop based Thread abstraction, and if you are a
75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//          thread running in the browser, there will likely be assumptions
85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//          that your thread will have an associated message loop.
95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This is a simple thread interface that backs to a native operating system
115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// thread.  You should use this only when you want a thread that does not have
125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// an associated MessageLoop.  Unittesting is the best example of this.
135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The simplest interface to use is DelegateSimpleThread, which will create
155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// a new thread, and execute the Delegate's virtual Run() in this new thread
165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// until it has completed, exiting the thread.
175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// NOTE: You *MUST* call Join on the thread to clean up the underlying thread
195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// resources.  You are also responsible for destructing the SimpleThread object.
205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// It is invalid to destroy a SimpleThread while it is running, or without
215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Start() having been called (and a thread never created).  The Delegate
225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// object should live as long as a DelegateSimpleThread.
235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Thread Safety: A SimpleThread is not completely thread safe.  It is safe to
255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// access it from the creating thread or from the newly created thread.  This
265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// implies that the creator thread should be the thread that calls Join.
275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Example:
295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   class MyThreadRunner : public DelegateSimpleThread::Delegate { ... };
305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   MyThreadRunner runner;
315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   DelegateSimpleThread thread(&runner, "good_name_here");
325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   thread.Start();
335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   // Start will return after the Thread has been successfully started and
345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   // initialized.  The newly created thread will invoke runner->Run(), and
355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   // run until it returns.
365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   thread.Join();  // Wait until the thread has exited.  You *MUST* Join!
375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   // The SimpleThread object is still valid, however you may not call Join
385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//   // or Start again.
395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef BASE_THREADING_SIMPLE_THREAD_H_
415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define BASE_THREADING_SIMPLE_THREAD_H_
425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string>
445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <queue>
455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <vector>
465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/base_export.h"
485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h"
495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/compiler_specific.h"
505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/threading/platform_thread.h"
515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/synchronization/lock.h"
525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/synchronization/waitable_event.h"
535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base {
555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This is the base SimpleThread.  You can derive from it and implement the
575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// virtual Run method, or you can use the DelegateSimpleThread interface.
585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT SimpleThread : public PlatformThread::Delegate {
595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public:
605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  class BASE_EXPORT Options {
615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   public:
625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    Options() : stack_size_(0) { }
635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    ~Options() { }
645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    // We use the standard compiler-supplied copy constructor.
665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    // A custom stack size, or 0 for the system default.
685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    void set_stack_size(size_t size) { stack_size_ = size; }
695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    size_t stack_size() const { return stack_size_; }
705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   private:
715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    size_t stack_size_;
725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  };
735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Create a SimpleThread.  |options| should be used to manage any specific
755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // configuration involving the thread creation and management.
765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Every thread has a name, in the form of |name_prefix|/TID, for example
775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // "my_thread/321".  The thread will not be created until Start() is called.
785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  explicit SimpleThread(const std::string& name_prefix);
795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  SimpleThread(const std::string& name_prefix, const Options& options);
805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual ~SimpleThread();
825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Start();
845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Join();
855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Subclasses should override the Run method.
875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Run() = 0;
885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return the thread name prefix, or "unnamed" if none was supplied.
905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  std::string name_prefix() { return name_prefix_; }
915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return the completed name including TID, only valid after Start().
935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  std::string name() { return name_; }
945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return the thread id, only valid after Start().
965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  PlatformThreadId tid() { return tid_; }
975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return True if Start() has ever been called.
995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  bool HasBeenStarted();
1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Return True if Join() has evern been called.
1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  bool HasBeenJoined() { return joined_; }
1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Overridden from PlatformThread::Delegate:
1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void ThreadMain() OVERRIDE;
1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Only set priorities with a careful understanding of the consequences.
1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // This is meant for very limited use cases.
1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  void SetThreadPriority(ThreadPriority priority) {
1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    PlatformThread::SetThreadPriority(thread_, priority);
1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  }
1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private:
1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  const std::string name_prefix_;
1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  std::string name_;
1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  const Options options_;
1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  PlatformThreadHandle thread_;  // PlatformThread handle, invalid after Join!
1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  WaitableEvent event_;          // Signaled if Start() was ever called.
1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  PlatformThreadId tid_;         // The backing thread's id.
1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  bool joined_;                  // True if Join has been called.
1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT DelegateSimpleThread : public SimpleThread {
1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public:
1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  class BASE_EXPORT Delegate {
1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   public:
1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    Delegate() { }
1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    virtual ~Delegate() { }
1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    virtual void Run() = 0;
1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  };
1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  DelegateSimpleThread(Delegate* delegate,
1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                       const std::string& name_prefix);
1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  DelegateSimpleThread(Delegate* delegate,
1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                       const std::string& name_prefix,
1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                       const Options& options);
1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual ~DelegateSimpleThread();
1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Run() OVERRIDE;
1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private:
1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  Delegate* delegate_;
1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// DelegateSimpleThreadPool allows you to start up a fixed number of threads,
1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// and then add jobs which will be dispatched to the threads.  This is
1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// convenient when you have a lot of small work that you want done
1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// multi-threaded, but don't want to spawn a thread for each small bit of work.
1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)//
1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// You just call AddWork() to add a delegate to the list of work to be done.
1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// JoinAll() will make sure that all outstanding work is processed, and wait
1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// for everything to finish.  You can reuse a pool, so you can call Start()
1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// again after you've called JoinAll().
1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT DelegateSimpleThreadPool
1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    : public DelegateSimpleThread::Delegate {
1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public:
1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  typedef DelegateSimpleThread::Delegate Delegate;
1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  DelegateSimpleThreadPool(const std::string& name_prefix, int num_threads);
1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual ~DelegateSimpleThreadPool();
1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Start up all of the underlying threads, and start processing work if we
1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // have any.
1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  void Start();
1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Make sure all outstanding work is finished, and wait for and destroy all
1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // of the underlying threads in the pool.
1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  void JoinAll();
1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // It is safe to AddWork() any time, before or after Start().
1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // Delegate* should always be a valid pointer, NULL is reserved internally.
1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  void AddWork(Delegate* work, int repeat_count);
1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  void AddWork(Delegate* work) {
1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)    AddWork(work, 1);
1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  }
1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  // We implement the Delegate interface, for running our internal threads.
1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  virtual void Run() OVERRIDE;
1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private:
1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  const std::string name_prefix_;
1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  int num_threads_;
1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  std::vector<DelegateSimpleThread*> threads_;
1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  std::queue<Delegate*> delegates_;
1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  base::Lock lock_;            // Locks delegates_
1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  WaitableEvent dry_;    // Not signaled when there is no work to do.
1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}  // namespace base
1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif  // BASE_THREADING_SIMPLE_THREAD_H_
191