Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#ifndef mozilla_dom_PromiseWorkerProxy_h
#define mozilla_dom_PromiseWorkerProxy_h
#include <cstdint>
#include "js/TypeDecls.h"
#include "mozilla/AlreadyAddRefed.h"
#include "mozilla/Mutex.h"
#include "mozilla/RefPtr.h"
#include "mozilla/dom/Promise.h"
#include "mozilla/dom/PromiseNativeHandler.h"
#include "mozilla/dom/StructuredCloneHolder.h"
#include "nsISupports.h"
struct JSStructuredCloneReader;
struct JSStructuredCloneWriter;
namespace JS {
class CloneDataPolicy;
} // namespace JS
namespace mozilla::dom {
class ThreadSafeWorkerRef;
class WorkerPrivate;
// A proxy to (eventually) mirror a resolved/rejected Promise's result from the
// main thread to a Promise on the worker thread.
//
// How to use:
//
// 1. Create a Promise on the worker thread and return it to the content
// script:
//
// RefPtr<Promise> promise =
// Promise::Create(workerPrivate->GlobalScope(), aRv);
// if (aRv.Failed()) {
// return nullptr;
// }
//
// 2. Create a PromiseWorkerProxy wrapping the Promise. If this fails, the
// worker is shutting down and you should fail the original call. This is
// only likely to happen in (Gecko-specific) worker onclose handlers.
//
// RefPtr<PromiseWorkerProxy> proxy =
// PromiseWorkerProxy::Create(workerPrivate, promise);
// if (!proxy) {
// // You may also reject the Promise with an AbortError or similar.
// return nullptr;
// }
//
// 3. Dispatch a runnable to the main thread, with a reference to the proxy to
// perform the main thread operation. PromiseWorkerProxy is thread-safe
// refcounted.
//
// 4. Return the worker thread promise to the JS caller:
//
// return promise.forget();
//
// 5. In your main thread runnable Run(), obtain a Promise on
// the main thread and call its AppendNativeHandler(PromiseNativeHandler*)
// to bind the PromiseWorkerProxy created at #2.
//
// 4. Then the Promise results returned by ResolvedCallback/RejectedCallback
// will be dispatched as a WorkerRunnable to the worker thread to
// resolve/reject the Promise created at #1.
//
// PromiseWorkerProxy can also be used in situations where there is no main
// thread Promise, or where special handling is required on the worker thread
// for promise resolution. Create a PromiseWorkerProxy as in steps 1 to 3
// above. When the main thread is ready to resolve the worker thread promise:
//
// 1. Acquire the mutex before attempting to access the worker private.
//
// AssertIsOnMainThread();
// MutexAutoLock lock(proxy->Lock());
// if (proxy->CleanedUp()) {
// // Worker has already shut down, can't access worker private.
// return;
// }
//
// 2. Dispatch a runnable to the worker. Use GetWorkerPrivate() to acquire the
// worker.
//
// RefPtr<FinishTaskWorkerRunnable> runnable =
// new FinishTaskWorkerRunnable(proxy->GetWorkerPrivate(), proxy,
// result);
// if (!r->Dispatch()) {
// // Worker is alive but not Running any more, so the Promise can't
// // be resolved, give up. The proxy will get Release()d at some
// // point.
//
// // Usually do nothing, but you may want to log the fact.
// }
//
// 3. In the WorkerRunnable's WorkerRun() use GetWorkerPromise() to access the
// Promise and resolve/reject it. Then call CleanUp().
//
// bool
// WorkerRun(JSContext* aCx, WorkerPrivate* aWorkerPrivate) override
// {
// aWorkerPrivate->AssertIsOnWorkerThread();
// RefPtr<Promise> promise = mProxy->GetWorkerPromise();
// promise->MaybeResolve(mResult);
// mProxy->CleanUp();
// }
//
// Note: If a PromiseWorkerProxy is not cleaned up by a WorkerRunnable - this
// can happen if the main thread Promise is never fulfilled - it will
// stay alive till the worker reaches a Canceling state, even if all external
// references to it are dropped.
class PromiseWorkerProxy : public PromiseNativeHandler,
public StructuredCloneHolderBase,
public SingleWriterLockOwner {
friend class PromiseWorkerProxyRunnable;
NS_DECL_THREADSAFE_ISUPPORTS
public:
typedef JSObject* (*ReadCallbackOp)(JSContext* aCx,
JSStructuredCloneReader* aReader,
const PromiseWorkerProxy* aProxy,
uint32_t aTag, uint32_t aData);
typedef bool (*WriteCallbackOp)(JSContext* aCx,
JSStructuredCloneWriter* aWorker,
PromiseWorkerProxy* aProxy,
JS::Handle<JSObject*> aObj);
bool OnWritingThread() const override;
struct PromiseWorkerProxyStructuredCloneCallbacks {
ReadCallbackOp Read;
WriteCallbackOp Write;
};
static already_AddRefed<PromiseWorkerProxy> Create(
WorkerPrivate* aWorkerPrivate, Promise* aWorkerPromise,
const PromiseWorkerProxyStructuredCloneCallbacks* aCallbacks = nullptr);
// Main thread callers must hold Lock() and check CleanUp() before calling
// this. Worker thread callers, this will assert that the proxy has not been
// cleaned up.
WorkerPrivate* GetWorkerPrivate() const MOZ_NO_THREAD_SAFETY_ANALYSIS;
// This should only be used within WorkerRunnable::WorkerRun() running on the
// worker thread! If this method is called after CleanUp(), return nullptr.
Promise* GetWorkerPromise() const;
// Worker thread only. Calling this invalidates several assumptions, so be
// sure this is the last thing you do.
// 1. WorkerPrivate() will no longer return a valid worker.
// 2. GetWorkerPromise() will return null!
void CleanUp();
Mutex& Lock() MOZ_RETURN_CAPABILITY(mCleanUpLock) { return mCleanUpLock; }
bool CleanedUp() const MOZ_REQUIRES(mCleanUpLock) {
mCleanUpLock.AssertCurrentThreadOwns();
return mCleanedUp;
}
// StructuredCloneHolderBase
JSObject* CustomReadHandler(JSContext* aCx, JSStructuredCloneReader* aReader,
const JS::CloneDataPolicy& aCloneDataPolicy,
uint32_t aTag, uint32_t aIndex) override;
bool CustomWriteHandler(JSContext* aCx, JSStructuredCloneWriter* aWriter,
JS::Handle<JSObject*> aObj,
bool* aSameProcessScopeRequired) override;
protected:
virtual void ResolvedCallback(JSContext* aCx, JS::Handle<JS::Value> aValue,
ErrorResult& aRv) override;
virtual void RejectedCallback(JSContext* aCx, JS::Handle<JS::Value> aValue,
ErrorResult& aRv) override;
private:
explicit PromiseWorkerProxy(
Promise* aWorkerPromise,
const PromiseWorkerProxyStructuredCloneCallbacks* aCallbacks = nullptr);
virtual ~PromiseWorkerProxy();
// Function pointer for calling Promise::{ResolveInternal,RejectInternal}.
typedef void (Promise::*RunCallbackFunc)(JSContext*, JS::Handle<JS::Value>);
void RunCallback(JSContext* aCx, JS::Handle<JS::Value> aValue,
RunCallbackFunc aFunc);
// Any thread with appropriate checks.
RefPtr<ThreadSafeWorkerRef> mWorkerRef;
// Worker thread only.
RefPtr<Promise> mWorkerPromise;
// Modified on the worker thread.
// It is ok to *read* this without a lock on the worker.
// Main thread must always acquire a lock.
bool mCleanedUp MOZ_GUARDED_BY(
mCleanUpLock); // To specify if the cleanUp() has been done.
const PromiseWorkerProxyStructuredCloneCallbacks* mCallbacks;
// Ensure the worker and the main thread won't race to access |mCleanedUp|.
// Should be a MutexSingleWriter, but that causes a lot of issues when you
// expose the lock via Lock().
Mutex mCleanUpLock;
};
} // namespace mozilla::dom
#endif // mozilla_dom_PromiseWorkerProxy_h