/* -*- 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/. */
/* * 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;
#ifdef DEBUG // In debug mode, provide a way for clients to annotate WorkerRefs # define SET_WORKERREF_DEBUG_STATUS(workerref, str) \
((workerref)->DebugSetWorkerRefStatus(str)) # define GET_WORKERREF_DEBUG_STATUS(workerref) \
((workerref)->DebugGetWorkerRefStatus()) #else # define SET_WORKERREF_DEBUG_STATUS(workerref, str) (void()) # define GET_WORKERREF_DEBUG_STATUS(workerref) (EmptyCString()) #endif
class StrongWorkerRef final : public WorkerRef { public: static already_AddRefed<StrongWorkerRef> Create(
WorkerPrivate* aWorkerPrivate, constchar* 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, constchar* aName);
// The count of background actors which binding with this IPCWorkerRef.
uint32_t mActorCount;
};
// 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);
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
