gecko-dev/xpcom/threads/CooperativeThreadPool.h

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_CooperativeThreadPool_h
#define mozilla_CooperativeThreadPool_h

#include "mozilla/Array.h"
#include "mozilla/CondVar.h"
#include "mozilla/Mutex.h"
#include "mozilla/ThreadLocal.h"
#include "mozilla/UniquePtr.h"
#include "mozilla/Variant.h"
#include "nsCOMPtr.h"
#include "nsThreadUtils.h"
#include "prthread.h"

// Windows silliness. winbase.h defines an empty no-argument Yield macro.
#undef Yield

class nsIEventTarget;

namespace mozilla {

// A CooperativeThreadPool is a pool of threads that process jobs, with at most
// one thread running at a given time. While processing a job, a thread can
// yield to another thread in the pool. Threads can be blocked on abstract
// Resources. When a thread yields, we iterate over all threads and look for
// one whose Resource has become available. It's possible that no thread is
// available to run, in which case all threads in the pool sleep. An outside
// thread can get things started again by calling RecheckBlockers (presumably
// after it has mutated some state that it expects would cause a Resource to
// become available).
class CooperativeThreadPool
{
public:
  // Every pool must have a controller object, on which callbacks are invoked.
  class Controller
  {
  public:
    // Called when a new thread in the pool is started. aIndex is the index of
    // the thread within the pool. aName is the thread name (e.g., Main#4), and
    // aStackTop is the guess for the address of the top of the stack. The
    // thread will begin processing events immediately after OnStartThread is called.
    virtual void OnStartThread(size_t aIndex, const nsACString& aName, void* aStackTop) = 0;

    // Called when a thread in the pool is about to be shut down.
    virtual void OnStopThread(size_t aIndex) = 0;

    // Threads in the pool are either suspended or running. At most one thread
    // will be running at any time. All other threads will be suspended.

    // Called when a thread is resumed (un-suspended). Note that OnResumeThread
    // will not be called if the thread is starting up. OnStartThread will be
    // called instead.
    virtual void OnResumeThread(size_t aIndex) = 0;

    // Called when a thread in the pool is about to be suspended. Note that
    // OnSuspendThread will not be called if the thread is shutting
    // down. OnStopThread is called instead.
    virtual void OnSuspendThread(size_t aIndex) = 0;
  };

  CooperativeThreadPool(size_t aNumThreads,
                        Mutex& aMutex,
                        Controller& aController);
  ~CooperativeThreadPool();

  void Shutdown();

  // An abstract class representing something that can be blocked on. Examples
  // are an event queue (where IsAvailable would check if the queue is
  // non-empty) or an object that can be owned by only one thread at a time
  // (where IsAvailable would check if the object is unowned).
  class Resource {
  public:
    virtual bool IsAvailable(const MutexAutoLock& aProofOfLock) = 0;
  };

  // Typically called by a thread outside the pool, this will check if any
  // thread is blocked on a resource that has become available. In this case,
  // the thread will resume. Nothing is done if some thread in the pool was
  // already running.
  void RecheckBlockers(const MutexAutoLock& aProofOfLock);

  // Must be called from within the thread pool. Causes the current thread to be
  // blocked on aBlocker, which can be null if the thread is ready to run
  // unconditionally.
  static void Yield(Resource* aBlocker, const MutexAutoLock& aProofOfLock);

  static bool IsCooperativeThread();

  enum class AllThreadsBlocked { Blocked };
  using SelectedThread = Variant<size_t, AllThreadsBlocked>;

  SelectedThread CurrentThreadIndex(const MutexAutoLock& aProofOfLock) const;

  static const size_t kMaxThreads = 16;

private:
  class CooperativeThread
  {
    friend class CooperativeThreadPool;

  public:
    CooperativeThread(CooperativeThreadPool* aPool,
                      size_t aIndex);

    void BeginShutdown();
    void EndShutdown();

    void Started();

    bool IsBlocked(const MutexAutoLock& aProofOfLock);
    void SetBlocker(Resource* aResource) { mBlocker = aResource; }

    void Yield(const MutexAutoLock& aProofOfLock);

  private:
    static void ThreadFunc(void* aArg);
    void ThreadMethod();

    CooperativeThreadPool* mPool;
    CondVar mCondVar;
    Resource* mBlocker;
    PRThread* mThread;
    nsCOMPtr<nsIEventTarget> mEventTarget;
    const size_t mIndex;
    bool mRunning;
  };

  class StartRunnable;

  Mutex& mMutex;
  CondVar mShutdownCondition;
  nsThreadPoolNaming mThreadNaming;

  bool mRunning;
  const size_t mNumThreads;
  size_t mRunningThreads;
  Controller& mController;
  Array<UniquePtr<CooperativeThread>, kMaxThreads> mThreads;

  SelectedThread mSelectedThread;

  static MOZ_THREAD_LOCAL(CooperativeThread*) sTlsCurrentThread;
};

} // namespace mozilla

#endif // mozilla_CooperativeThreadPool_h