diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 01:47:29 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 01:47:29 +0000 |
commit | 0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d (patch) | |
tree | a31f07c9bcca9d56ce61e9a1ffd30ef350d513aa /dom/workers/WorkerRef.h | |
parent | Initial commit. (diff) | |
download | firefox-esr-0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d.tar.xz firefox-esr-0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d.zip |
Adding upstream version 115.8.0esr.upstream/115.8.0esr
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'dom/workers/WorkerRef.h')
-rw-r--r-- | dom/workers/WorkerRef.h | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/dom/workers/WorkerRef.h b/dom/workers/WorkerRef.h new file mode 100644 index 0000000000..decee3994e --- /dev/null +++ b/dom/workers/WorkerRef.h @@ -0,0 +1,237 @@ +/* -*- 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_dom_workers_WorkerRef_h +#define mozilla_dom_workers_WorkerRef_h + +#include "mozilla/dom/WorkerStatus.h" +#include "mozilla/MoveOnlyFunction.h" +#include "mozilla/RefPtr.h" +#include "nsISupports.h" + +namespace mozilla::dom { + +/* + * If you want to play with a DOM Worker, you must know that it can go away + * at any time if nothing prevents its shutting down. This documentation helps + * to understand how to play with DOM Workers correctly. + * + * There are several reasons why a DOM Worker could go away. Here is the + * complete list: + * + * a. GC/CC - If the DOM Worker thread is idle and the Worker object is garbage + * collected, it goes away. + * b. The worker script can call self.close() + * c. The Worker object calls worker.terminate() + * d. Firefox is shutting down. + * + * When a DOM Worker goes away, it does several steps. See more in + * WorkerStatus.h. The DOM Worker thread will basically stop scheduling + * WorkerRunnables, and eventually WorkerControlRunnables. But if there is + * something preventing the shutting down, it will always possible to dispatch + * WorkerControlRunnables. Of course, at some point, the worker _must_ be + * released, otherwise firefox will leak it and the browser shutdown will hang. + * + * WeakWorkerRef is a refcounted, NON thread-safe object. + * + * From this object, you can obtain a WorkerPrivate, calling + * WeakWorkerRef::GetPrivate(). It returns nullptr if the worker is shutting + * down or if it is already gone away. + * + * If you want to know when a DOM Worker starts the shutting down procedure, + * pass a callback to the mozilla::dom::WeakWorkerRef::Create() method. + * Your function will be called. Note that _after_ the callback, + * WeakWorkerRef::GetPrivate() will return nullptr. + * + * How to keep a DOM Worker alive? + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * If you need to keep the worker alive, you must use StrongWorkerRef. + * You can have this refcounted, NON thread-safe object, calling + * mozilla::dom::StrongWorkerRef::Create(WorkerPrivate* aWorkerPrivate); + * + * If you have a StrongWorkerRef: + * a. the DOM Worker is kept alive. + * b. you can have access to the WorkerPrivate, calling: Private(). + * c. WorkerControlRunnable can be dispatched. + * + * Note that the DOM Worker shutdown can start at any time, but having a + * StrongWorkerRef prevents the full shutdown. Also with StrongWorkerRef, you + * can pass a callback when calling mozilla::dom::StrongWorkerRef::Create(). + * + * When the DOM Worker shutdown starts, WorkerRunnable cannot be dispatched + * anymore. At this point, you should dispatch WorkerControlRunnable just to + * release resources. + * + * How to have a thread-safe DOM Worker reference? + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * Sometimes you need to play with threads and you need a thread-safe worker + * reference. ThreadSafeWorkerRef is what you want. + * + * Just because this object can be sent to different threads, we don't allow the + * setting of a callback. It would be confusing. + * + * ThreadSafeWorkerRef can be destroyed in any thread. Internally it keeps a + * reference to its StrongWorkerRef creator and this ref will be dropped on the + * correct thread when the ThreadSafeWorkerRef is deleted. + * + * IPC WorkerRef + * ~~~~~~~~~~~~~ + * + * IPDL protocols require a correct shutdown sequence. Because of this, they + * need a special configuration: + * 1. they need to be informed when the Worker starts the shutting down + * 2. they don't want to prevent the shutdown + * 3. but at the same time, they need to block the shutdown until the WorkerRef + * is not longer alive. + * + * Point 1 is a standard feature of WorkerRef; point 2 is similar to + * WeakWorkerRef; point 3 is similar to StrongWorkerRef. + * + * You can create a special IPC WorkerRef using this static method: + * mozilla::dom::IPCWorkerRef::Create(WorkerPrivate* aWorkerPrivate, + * const char* * aName); + */ + +class WorkerPrivate; +class StrongWorkerRef; +class ThreadSafeWorkerRef; + +class WorkerRef { + friend class WorkerPrivate; + + public: + NS_INLINE_DECL_REFCOUNTING(WorkerRef) + + protected: + WorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName, + bool aIsPreventingShutdown); + virtual ~WorkerRef(); + + virtual void Notify(); + + bool HoldWorker(WorkerStatus aStatus); + void ReleaseWorker(); + + bool IsPreventingShutdown() const { return mIsPreventingShutdown; } + + const char* Name() const { return mName; } + + WorkerPrivate* mWorkerPrivate; + + MoveOnlyFunction<void()> mCallback; + const char* const mName; + const bool mIsPreventingShutdown; + + // True if this WorkerRef has been added to a WorkerPrivate. + bool mHolding; +}; + +class WeakWorkerRef final : public WorkerRef { + public: + static already_AddRefed<WeakWorkerRef> Create( + WorkerPrivate* aWorkerPrivate, + MoveOnlyFunction<void()>&& aCallback = nullptr); + + WorkerPrivate* GetPrivate() const; + + // This can be called on any thread. It's racy and, in general, the wrong + // choice. + WorkerPrivate* GetUnsafePrivate() const; + + private: + explicit WeakWorkerRef(WorkerPrivate* aWorkerPrivate); + ~WeakWorkerRef(); + + void Notify() override; +}; + +class StrongWorkerRef final : public WorkerRef { + public: + static already_AddRefed<StrongWorkerRef> Create( + WorkerPrivate* aWorkerPrivate, const char* aName, + MoveOnlyFunction<void()>&& aCallback = nullptr); + + // This function creates a StrongWorkerRef even when in the Canceling state of + // the worker's lifecycle. It's intended to be used by system code, e.g. code + // that needs to perform IPC. + // + // This method should only be used in cases where the StrongWorkerRef will be + // used for an extremely bounded duration that cannot be impacted by content. + // For example, IPCStreams use this type of ref in order to immediately + // migrate to an actor on another thread. Whether the IPCStream ever actually + // is streamed does not matter; the ref will be dropped once the new actor is + // created. For this reason, this method does not take a callback. It's + // expected and required that callers will drop the reference when they are + // done. + static already_AddRefed<StrongWorkerRef> CreateForcibly( + WorkerPrivate* aWorkerPrivate, const char* aName); + + WorkerPrivate* Private() const; + + private: + friend class WeakWorkerRef; + friend class ThreadSafeWorkerRef; + + static already_AddRefed<StrongWorkerRef> CreateImpl( + WorkerPrivate* aWorkerPrivate, const char* aName, + WorkerStatus aFailStatus); + + StrongWorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName); + ~StrongWorkerRef(); +}; + +class ThreadSafeWorkerRef final { + public: + NS_INLINE_DECL_THREADSAFE_REFCOUNTING(ThreadSafeWorkerRef) + + explicit ThreadSafeWorkerRef(StrongWorkerRef* aRef); + + WorkerPrivate* Private() const; + + private: + friend class StrongWorkerRef; + + ~ThreadSafeWorkerRef(); + + RefPtr<StrongWorkerRef> mRef; +}; + +class IPCWorkerRef final : public WorkerRef { + public: + static already_AddRefed<IPCWorkerRef> Create( + WorkerPrivate* aWorkerPrivate, const char* aName, + MoveOnlyFunction<void()>&& aCallback = nullptr); + + WorkerPrivate* Private() const; + + private: + IPCWorkerRef(WorkerPrivate* aWorkerPrivate, const char* aName); + ~IPCWorkerRef(); +}; + +// Template class to keep an Actor pointer, as a raw pointer, in a ref-counted +// way when passed to lambdas. +template <class ActorPtr> +class IPCWorkerRefHelper final { + public: + NS_INLINE_DECL_REFCOUNTING(IPCWorkerRefHelper); + + explicit IPCWorkerRefHelper(ActorPtr* aActor) : mActor(aActor) {} + + ActorPtr* Actor() const { return mActor; } + + private: + ~IPCWorkerRefHelper() = default; + + // Raw pointer + ActorPtr* mActor; +}; + +} // namespace mozilla::dom + +#endif /* mozilla_dom_workers_WorkerRef_h */ |