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