dom/workers/WorkerRef.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 mozilla_dom_workers_WorkerRef_h
   8 #define mozilla_dom_workers_WorkerRef_h
   9
  10 #include "mozilla/dom/WorkerStatus.h"
  11 #include "mozilla/MoveOnlyFunction.h"
  12 #include "mozilla/RefPtr.h"
  13 #include "nsISupports.h"
  14 #include "nsTString.h"
  15
  16 #ifdef DEBUG
  17 #  include "mozilla/Mutex.h"
  18 #endif
  19
  20 namespace mozilla::dom {
  21
  22 /*
  23  * If you want to play with a DOM Worker, you must know that it can go away
  24  * at any time if nothing prevents its shutting down. This documentation helps
  25  * to understand how to play with DOM Workers correctly.
  26  *
  27  * There are several reasons why a DOM Worker could go away. Here is the
  28  * complete list:
  29  *
  30  * a. GC/CC - If the DOM Worker thread is idle and the Worker object is garbage
  31  *    collected, it goes away.
  32  * b. The worker script can call self.close()
  33  * c. The Worker object calls worker.terminate()
  34  * d. Firefox is shutting down.
  35  *
  36  * When a DOM Worker goes away, it does several steps. See more in
  37  * WorkerStatus.h. The DOM Worker thread will basically stop scheduling
  38  * WorkerRunnables, and eventually WorkerControlRunnables. But if there is
  39  * something preventing the shutting down, it will always possible to dispatch
  40  * WorkerControlRunnables.  Of course, at some point, the worker _must_ be
  41  * released, otherwise firefox will leak it and the browser shutdown will hang.
  42  *
  43  * WeakWorkerRef is a refcounted, NON thread-safe object.
  44  *
  45  * From this object, you can obtain a WorkerPrivate, calling
  46  * WeakWorkerRef::GetPrivate(). It returns nullptr if the worker is shutting
  47  * down or if it is already gone away.
  48  *
  49  * If you want to know when a DOM Worker starts the shutting down procedure,
  50  * pass a callback to the mozilla::dom::WeakWorkerRef::Create() method.
  51  * Your function will be called. Note that _after_ the callback,
  52  * WeakWorkerRef::GetPrivate() will return nullptr.
  53  *
  54  * How to keep a DOM Worker alive?
  55  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56  *
  57  * If you need to keep the worker alive, you must use StrongWorkerRef.
  58  * You can have this refcounted, NON thread-safe object, calling
  59  * mozilla::dom::StrongWorkerRef::Create(WorkerPrivate* aWorkerPrivate);
  60  *
  61  * If you have a StrongWorkerRef:
  62  * a. the DOM Worker is kept alive.
  63  * b. you can have access to the WorkerPrivate, calling: Private().
  64  * c. WorkerControlRunnable can be dispatched.
  65  *
  66  * Note that the DOM Worker shutdown can start at any time, but having a
  67  * StrongWorkerRef prevents the full shutdown. Also with StrongWorkerRef, you
  68  * can pass a callback when calling mozilla::dom::StrongWorkerRef::Create().
  69  *
  70  * When the DOM Worker shutdown starts, WorkerRunnable cannot be dispatched
  71  * anymore. At this point, you should dispatch WorkerControlRunnable just to
  72  * release resources.
  73  *
  74  * How to have a thread-safe DOM Worker reference?
  75  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76  *
  77  * Sometimes you need to play with threads and you need a thread-safe worker
  78  * reference. ThreadSafeWorkerRef is what you want.
  79  *
  80  * Just because this object can be sent to different threads, we don't allow the
  81  * setting of a callback. It would be confusing.
  82  *
  83  * ThreadSafeWorkerRef can be destroyed in any thread. Internally it keeps a
  84  * reference to its StrongWorkerRef creator and this ref will be dropped on the
  85  * correct thread when the ThreadSafeWorkerRef is deleted.
  86  *
  87  * IPC WorkerRef
  88  * ~~~~~~~~~~~~~
  89  *
  90  * IPDL protocols require a correct shutdown sequence. Because of this, they
  91  * need a special configuration:
  92  * 1. they need to be informed when the Worker starts the shutting down
  93  * 2. they don't want to prevent the shutdown
  94  * 3. but at the same time, they need to block the shutdown until the WorkerRef
  95  *    is not longer alive.
  96  *
  97  * Point 1 is a standard feature of WorkerRef; point 2 is similar to
  98  * WeakWorkerRef; point 3 is similar to StrongWorkerRef.
  99  *
 100  * You can create a special IPC WorkerRef using this static method:
 101  * mozilla::dom::IPCWorkerRef::Create(WorkerPrivate* aWorkerPrivate,
 102  *                                    const char* * aName);
 103  */
 104
 105 class WorkerPrivate;
 106 class StrongWorkerRef;
 107 class ThreadSafeWorkerRef;
 108
 109 #ifdef DEBUG  // In debug mode, provide a way for clients to annotate WorkerRefs
 110 #  define SET_WORKERREF_DEBUG_STATUS(workerref, str) \
 111     ((workerref)->DebugSetWorkerRefStatus(str))
 112 #  define GET_WORKERREF_DEBUG_STATUS(workerref) \
 113     ((workerref)->DebugGetWorkerRefStatus())
 114 #else
 115 #  define SET_WORKERREF_DEBUG_STATUS(workerref, str) (void())
 116 #  define GET_WORKERREF_DEBUG_STATUS(workerref) (EmptyCString())
 117 #endif
 118
 119 class WorkerRef {
 120   friend class WorkerPrivate;
 121
 122  public:
 123   NS_INLINE_DECL_REFCOUNTING(WorkerRef)
 124
 125 #ifdef DEBUG
 126   mutable Mutex mDebugMutex;
 127   nsCString mDebugStatus MOZ_GUARDED_BY(mDebugMutex);
 128
 129   void DebugSetWorkerRefStatus(const nsCString& aStatus) {
 130     MutexAutoLock lock(mDebugMutex);
 131     mDebugStatus = aStatus;
 132   }
 133
 134   const nsCString DebugGetWorkerRefStatus() const {
 135     MutexAutoLock lock(mDebugMutex);
 136     return mDebugStatus;
 137   }
 138 #endif
 139
 140  protected:
 141   WorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName,
 142             bool aIsPreventingShutdown);
 143   virtual ~WorkerRef();
 144
 145   virtual void Notify();
 146
 147   bool HoldWorker(WorkerStatus aStatus);
 148   void ReleaseWorker();
 149
 150   bool IsPreventingShutdown() const { return mIsPreventingShutdown; }
 151
 152   const char* Name() const { return mName; }
 153
 154   WorkerPrivate* mWorkerPrivate;
 155
 156   MoveOnlyFunction<void()> mCallback;
 157   const char* const mName;
 158   const bool mIsPreventingShutdown;
 159
 160   // True if this WorkerRef has been added to a WorkerPrivate.
 161   bool mHolding;
 162 };
 163
 164 class WeakWorkerRef final : public WorkerRef {
 165  public:
 166   static already_AddRefed<WeakWorkerRef> Create(
 167       WorkerPrivate* aWorkerPrivate,
 168       MoveOnlyFunction<void()>&& aCallback = nullptr);
 169
 170   WorkerPrivate* GetPrivate() const;
 171
 172   // This can be called on any thread. It's racy and, in general, the wrong
 173   // choice.
 174   WorkerPrivate* GetUnsafePrivate() const;
 175
 176  private:
 177   explicit WeakWorkerRef(WorkerPrivate* aWorkerPrivate);
 178   ~WeakWorkerRef();
 179
 180   void Notify() override;
 181 };
 182
 183 class StrongWorkerRef final : public WorkerRef {
 184  public:
 185   static already_AddRefed<StrongWorkerRef> Create(
 186       WorkerPrivate* aWorkerPrivate, const char* aName,
 187       MoveOnlyFunction<void()>&& aCallback = nullptr);
 188
 189   // This function creates a StrongWorkerRef even when in the Canceling state of
 190   // the worker's lifecycle. It's intended to be used by system code, e.g. code
 191   // that needs to perform IPC.
 192   //
 193   // This method should only be used in cases where the StrongWorkerRef will be
 194   // used for an extremely bounded duration that cannot be impacted by content.
 195   // For example, IPCStreams use this type of ref in order to immediately
 196   // migrate to an actor on another thread. Whether the IPCStream ever actually
 197   // is streamed does not matter; the ref will be dropped once the new actor is
 198   // created. For this reason, this method does not take a callback. It's
 199   // expected and required that callers will drop the reference when they are
 200   // done.
 201   static already_AddRefed<StrongWorkerRef> CreateForcibly(
 202       WorkerPrivate* aWorkerPrivate, const char* aName);
 203
 204   WorkerPrivate* Private() const;
 205
 206  private:
 207   friend class WeakWorkerRef;
 208   friend class ThreadSafeWorkerRef;
 209
 210   static already_AddRefed<StrongWorkerRef> CreateImpl(
 211       WorkerPrivate* aWorkerPrivate, const char* aName,
 212       WorkerStatus aFailStatus);
 213
 214   StrongWorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName);
 215   ~StrongWorkerRef();
 216 };
 217
 218 class ThreadSafeWorkerRef final {
 219  public:
 220   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(ThreadSafeWorkerRef)
 221
 222   explicit ThreadSafeWorkerRef(StrongWorkerRef* aRef);
 223
 224   WorkerPrivate* Private() const;
 225
 226 #ifdef DEBUG
 227   RefPtr<StrongWorkerRef>& Ref() { return mRef; }
 228 #endif
 229
 230  private:
 231   friend class StrongWorkerRef;
 232
 233   ~ThreadSafeWorkerRef();
 234
 235   RefPtr<StrongWorkerRef> mRef;
 236 };
 237
 238 class IPCWorkerRef final : public WorkerRef {
 239  public:
 240   static already_AddRefed<IPCWorkerRef> Create(
 241       WorkerPrivate* aWorkerPrivate, const char* aName,
 242       MoveOnlyFunction<void()>&& aCallback = nullptr);
 243
 244   WorkerPrivate* Private() const;
 245
 246   void SetActorCount(uint32_t aCount);
 247
 248  private:
 249   IPCWorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName);
 250   ~IPCWorkerRef();
 251
 252   // The count of background actors which binding with this IPCWorkerRef.
 253   uint32_t mActorCount;
 254 };
 255
 256 // Template class to keep an Actor pointer, as a raw pointer, in a ref-counted
 257 // way when passed to lambdas.
 258 template <class ActorPtr>
 259 class IPCWorkerRefHelper final {
 260  public:
 261   NS_INLINE_DECL_REFCOUNTING(IPCWorkerRefHelper);
 262
 263   explicit IPCWorkerRefHelper(ActorPtr* aActor) : mActor(aActor) {}
 264
 265   ActorPtr* Actor() const { return mActor; }
 266
 267  private:
 268   ~IPCWorkerRefHelper() = default;
 269
 270   // Raw pointer
 271   ActorPtr* mActor;
 272 };
 273
 274 }  // namespace mozilla::dom
 275
 276 #endif /* mozilla_dom_workers_WorkerRef_h */