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