xpcom/threads/SharedThreadPool.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef SharedThreadPool_h_
   8 #define SharedThreadPool_h_
   9
  10 #include <utility>
  11 #include <type_traits>
  12 #include "mozilla/AlreadyAddRefed.h"
  13 #include "mozilla/RefCountType.h"
  14 #include "nsCOMPtr.h"
  15 #include "nsID.h"
  16 #include "nsIThreadPool.h"
  17 #include "nsString.h"
  18 #include "nscore.h"
  19
  20 class nsIRunnable;
  21
  22 namespace mozilla {
  23
  24 // Wrapper that makes an nsIThreadPool a singleton, and provides a
  25 // consistent threadsafe interface to get instances. Callers simply get a
  26 // SharedThreadPool by the name of its nsIThreadPool. All get requests of
  27 // the same name get the same SharedThreadPool. Users must store a reference
  28 // to the pool, and when the last reference to a SharedThreadPool is dropped
  29 // the pool is shutdown and deleted. Users aren't required to manually
  30 // shutdown the pool, and can release references on any thread. This can make
  31 // it significantly easier to use thread pools, because the caller doesn't need
  32 // to worry about joining and tearing it down.
  33 //
  34 // On Windows all threads in the pool have MSCOM initialized with
  35 // COINIT_MULTITHREADED. Note that not all users of MSCOM use this mode see [1],
  36 // and mixing MSCOM objects between the two is terrible for performance, and can
  37 // cause some functions to fail. So be careful when using Win32 APIs on a
  38 // SharedThreadPool, and avoid sharing objects if at all possible.
  39 //
  40 // [1]
  41 // https://searchfox.org/mozilla-central/search?q=coinitialize&redirect=false
  42 class SharedThreadPool : public nsIThreadPool {
  43  public:
  44   // Gets (possibly creating) the shared thread pool singleton instance with
  45   // thread pool named aName.
  46   static already_AddRefed<SharedThreadPool> Get(const nsCString& aName,
  47                                                 uint32_t aThreadLimit = 4);
  48
  49   // We implement custom threadsafe AddRef/Release pair, that destroys the
  50   // the shared pool singleton when the refcount drops to 0. The addref/release
  51   // are implemented using locking, so it's not recommended that you use them
  52   // in a tight loop.
  53   NS_IMETHOD QueryInterface(REFNSIID aIID, void** aInstancePtr) override;
  54   NS_IMETHOD_(MozExternalRefCountType) AddRef(void) override;
  55   NS_IMETHOD_(MozExternalRefCountType) Release(void) override;
  56   using HasThreadSafeRefCnt = std::true_type;
  57
  58   // Forward behaviour to wrapped thread pool implementation.
  59   NS_FORWARD_SAFE_NSITHREADPOOL(mPool);
  60
  61   // Call this when dispatching from an event on the same
  62   // threadpool that is about to complete. We should not create a new thread
  63   // in that case since a thread is about to become idle.
  64   nsresult DispatchFromEndOfTaskInThisPool(nsIRunnable* event) {
  65     return Dispatch(event, NS_DISPATCH_AT_END);
  66   }
  67
  68   NS_IMETHOD DispatchFromScript(nsIRunnable* event, uint32_t flags) override {
  69     return Dispatch(event, flags);
  70   }
  71
  72   NS_IMETHOD Dispatch(already_AddRefed<nsIRunnable> event,
  73                       uint32_t flags = NS_DISPATCH_NORMAL) override {
  74     return !mPool ? NS_ERROR_NULL_POINTER
  75                   : mPool->Dispatch(std::move(event), flags);
  76   }
  77
  78   NS_IMETHOD DelayedDispatch(already_AddRefed<nsIRunnable>, uint32_t) override {
  79     return NS_ERROR_NOT_IMPLEMENTED;
  80   }
  81
  82   using nsIEventTarget::Dispatch;
  83
  84   NS_IMETHOD RegisterShutdownTask(nsITargetShutdownTask* task) override {
  85     return NS_ERROR_NOT_IMPLEMENTED;
  86   }
  87
  88   NS_IMETHOD UnregisterShutdownTask(nsITargetShutdownTask* task) override {
  89     return NS_ERROR_NOT_IMPLEMENTED;
  90   }
  91
  92   NS_IMETHOD IsOnCurrentThread(bool* _retval) override {
  93     return !mPool ? NS_ERROR_NULL_POINTER : mPool->IsOnCurrentThread(_retval);
  94   }
  95
  96   NS_IMETHOD_(bool) IsOnCurrentThreadInfallible() override {
  97     return mPool && mPool->IsOnCurrentThread();
  98   }
  99
 100   // Creates necessary statics. Called once at startup.
 101   static void InitStatics();
 102
 103   // Spins the event loop until all thread pools are shutdown.
 104   // *Must* be called on the main thread.
 105   static void SpinUntilEmpty();
 106
 107  private:
 108   // Returns whether there are no pools in existence at the moment.
 109   static bool IsEmpty();
 110
 111   // Creates a singleton SharedThreadPool wrapper around aPool.
 112   // aName is the name of the aPool, and is used to lookup the
 113   // SharedThreadPool in the hash table of all created pools.
 114   SharedThreadPool(const nsCString& aName, nsIThreadPool* aPool);
 115   virtual ~SharedThreadPool();
 116
 117   nsresult EnsureThreadLimitIsAtLeast(uint32_t aThreadLimit);
 118
 119   // Name of mPool.
 120   const nsCString mName;
 121
 122   // Thread pool being wrapped.
 123   nsCOMPtr<nsIThreadPool> mPool;
 124
 125   // Refcount. We implement custom ref counting so that the thread pool is
 126   // shutdown in a threadsafe manner and singletonness is preserved.
 127   nsrefcnt mRefCnt;
 128 };
 129
 130 }  // namespace mozilla
 131
 132 #endif  // SharedThreadPool_h_