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 file,
#ifndef mozilla_dom_Promise_h
#define mozilla_dom_Promise_h
#include <functional>
#include <type_traits>
#include <utility>
#include "ErrorList.h"
#include "js/RootingAPI.h"
#include "js/TypeDecls.h"
#include "mozilla/AlreadyAddRefed.h"
#include "mozilla/Assertions.h"
#include "mozilla/ErrorResult.h"
#include "mozilla/RefPtr.h"
#include "mozilla/Result.h"
#include "mozilla/WeakPtr.h"
#include "mozilla/dom/AutoEntryScript.h"
#include "mozilla/dom/ScriptSettings.h"
#include "mozilla/dom/ToJSValue.h"
#include "nsCycleCollectionParticipant.h"
#include "nsError.h"
#include "nsISupports.h"
#include "nsString.h"
class nsCycleCollectionTraversalCallback;
class nsIGlobalObject;
namespace JS {
class Value;
}
namespace mozilla::dom {
class AnyCallback;
class MediaStreamError;
class PromiseInit;
class PromiseNativeHandler;
class PromiseDebugging;
class Promise : public SupportsWeakPtr {
friend class PromiseTask;
friend class PromiseWorkerProxy;
friend class PromiseWorkerProxyRunnable;
public:
NS_INLINE_DECL_CYCLE_COLLECTING_NATIVE_REFCOUNTING(Promise)
NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_NATIVE_CLASS(Promise)
enum PropagateUserInteraction {
eDontPropagateUserInteraction,
ePropagateUserInteraction
};
// Promise creation tries to create a JS reflector for the Promise, so is
// fallible. Furthermore, we don't want to do JS-wrapping on a 0-refcount
// object, so we addref before doing that and return the addrefed pointer
// here.
// Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
// the promise resolve handler to be called as if we were handling user
// input events in case we are currently handling user input events.
static already_AddRefed<Promise> Create(
nsIGlobalObject* aGlobal, ErrorResult& aRv,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
// Same as Promise::Create but never throws, but instead:
// 1. Causes crash on OOM (as nearly every other web APIs do)
// 2. Silently creates a no-op Promise if the JS context is shut down
// This can be useful for implementations that produce promises but do not
// care whether the current global is alive to consume them.
// Note that PromiseObj() can return a nullptr if created this way.
static already_AddRefed<Promise> CreateInfallible(
nsIGlobalObject* aGlobal,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
// Reports a rejected Promise by sending an error report.
static void ReportRejectedPromise(JSContext* aCx,
JS::Handle<JSObject*> aPromise);
using MaybeFunc = void (Promise::*)(JSContext*, JS::Handle<JS::Value>);
// Helpers for using Promise from C++.
// Most DOM objects are handled already. To add a new type T, add a
// ToJSValue overload in ToJSValue.h.
// aArg is a const reference so we can pass rvalues like integer constants
template <typename T>
void MaybeResolve(T&& aArg) {
MaybeSomething(std::forward<T>(aArg), &Promise::MaybeResolve);
}
void MaybeResolveWithUndefined();
void MaybeReject(JS::Handle<JS::Value> aValue) {
MaybeSomething(aValue, &Promise::MaybeReject);
}
// This method is deprecated. Consumers should MaybeRejectWithDOMException if
// they are rejecting with a DOMException, or use one of the other
// MaybeReject* methods otherwise. If they have a random nsresult which may
// or may not correspond to a DOMException type, they should consider using an
// appropriate DOMException-type nsresult with an informative message and
// calling MaybeRejectWithDOMException.
inline void MaybeReject(nsresult aArg) {
MOZ_ASSERT(NS_FAILED(aArg));
MaybeSomething(aArg, &Promise::MaybeReject);
}
inline void MaybeReject(ErrorResult&& aArg) {
MOZ_ASSERT(aArg.Failed());
MaybeSomething(std::move(aArg), &Promise::MaybeReject);
// That should have consumed aArg.
MOZ_ASSERT(!aArg.Failed());
}
void MaybeReject(const RefPtr<MediaStreamError>& aArg);
void MaybeRejectWithUndefined();
void MaybeResolveWithClone(JSContext* aCx, JS::Handle<JS::Value> aValue);
void MaybeRejectWithClone(JSContext* aCx, JS::Handle<JS::Value> aValue);
// Facilities for rejecting with various spec-defined exception values.
#define DOMEXCEPTION(name, err) \
inline void MaybeRejectWith##name(const nsACString& aMessage) { \
ErrorResult res; \
res.Throw##name(aMessage); \
MaybeReject(std::move(res)); \
} \
template <int N> \
void MaybeRejectWith##name(const char(&aMessage)[N]) { \
MaybeRejectWith##name(nsLiteralCString(aMessage)); \
}
#include "mozilla/dom/DOMExceptionNames.h"
#undef DOMEXCEPTION
template <ErrNum errorNumber, typename... Ts>
void MaybeRejectWithTypeError(Ts&&... aMessageArgs) {
ErrorResult res;
res.ThrowTypeError<errorNumber>(std::forward<Ts>(aMessageArgs)...);
MaybeReject(std::move(res));
}
inline void MaybeRejectWithTypeError(const nsACString& aMessage) {
ErrorResult res;
res.ThrowTypeError(aMessage);
MaybeReject(std::move(res));
}
template <int N>
void MaybeRejectWithTypeError(const char (&aMessage)[N]) {
MaybeRejectWithTypeError(nsLiteralCString(aMessage));
}
template <ErrNum errorNumber, typename... Ts>
void MaybeRejectWithRangeError(Ts&&... aMessageArgs) {
ErrorResult res;
res.ThrowRangeError<errorNumber>(std::forward<Ts>(aMessageArgs)...);
MaybeReject(std::move(res));
}
inline void MaybeRejectWithRangeError(const nsACString& aMessage) {
ErrorResult res;
res.ThrowRangeError(aMessage);
MaybeReject(std::move(res));
}
template <int N>
void MaybeRejectWithRangeError(const char (&aMessage)[N]) {
MaybeRejectWithRangeError(nsLiteralCString(aMessage));
}
// DO NOT USE MaybeRejectBrokenly with in new code. Promises should be
// rejected with Error instances.
// Note: MaybeRejectBrokenly is a template so we can use it with DOMException
// without instantiating the DOMException specialization of MaybeSomething in
// every translation unit that includes this header, because that would
// require use to include DOMException.h either here or in all those
// translation units.
template <typename T>
void MaybeRejectBrokenly(const T& aArg); // Not implemented by default; see
// specializations in the .cpp for
// the T values we support.
// If the JSContext has a pending exception then this will reject the promise
// with that exception and clear it from the JSContext.
void MaybeRejectWithExceptionFromContext(JSContext* aCx) {
HandleException(aCx);
}
// Mark a settled promise as already handled so that rejections will not
// be reported as unhandled.
bool SetSettledPromiseIsHandled();
// Mark a promise as handled so that rejections will not be reported as
// unhandled. Consider using SetSettledPromiseIsHandled if this promise is
// expected to be settled.
[[nodiscard]] bool SetAnyPromiseIsHandled();
// WebIDL
nsIGlobalObject* GetParentObject() const { return GetGlobalObject(); }
// Do the equivalent of Promise.resolve in the compartment of aGlobal. The
// compartment of aCx is ignored. Errors are reported on the ErrorResult; if
// aRv comes back !Failed(), this function MUST return a non-null value.
// Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
// the promise resolve handler to be called as if we were handling user
// input events in case we are currently handling user input events.
static already_AddRefed<Promise> Resolve(
nsIGlobalObject* aGlobal, JSContext* aCx, JS::Handle<JS::Value> aValue,
ErrorResult& aRv,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
// Do the equivalent of Promise.reject in the compartment of aGlobal. The
// compartment of aCx is ignored. Errors are reported on the ErrorResult; if
// aRv comes back !Failed(), this function MUST return a non-null value.
static already_AddRefed<Promise> Reject(nsIGlobalObject* aGlobal,
JSContext* aCx,
JS::Handle<JS::Value> aValue,
ErrorResult& aRv);
template <typename T>
static already_AddRefed<Promise> Reject(nsIGlobalObject* aGlobal, T&& aValue,
ErrorResult& aError) {
AutoJSAPI jsapi;
if (!jsapi.Init(aGlobal)) {
aError.Throw(NS_ERROR_UNEXPECTED);
return nullptr;
}
JSContext* cx = jsapi.cx();
JS::Rooted<JS::Value> val(cx);
if (!ToJSValue(cx, std::forward<T>(aValue), &val)) {
return Promise::RejectWithExceptionFromContext(aGlobal, cx, aError);
}
return Reject(aGlobal, cx, val, aError);
}
static already_AddRefed<Promise> RejectWithExceptionFromContext(
nsIGlobalObject* aGlobal, JSContext* aCx, ErrorResult& aError);
// Do the equivalent of Promise.all in the current compartment of aCx. Errors
// are reported on the ErrorResult; if aRv comes back !Failed(), this function
// MUST return a non-null value.
// Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
// the promise resolve handler to be called as if we were handling user
// input events in case we are currently handling user input events.
static already_AddRefed<Promise> All(
JSContext* aCx, const nsTArray<RefPtr<Promise>>& aPromiseList,
ErrorResult& aRv,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
template <typename Callback, typename... Args>
using IsHandlerCallback =
std::is_same<already_AddRefed<Promise>,
decltype(std::declval<Callback>()(
(JSContext*)(nullptr),
std::declval<JS::Handle<JS::Value>>(),
std::declval<ErrorResult&>(), std::declval<Args>()...))>;
template <typename Callback, typename... Args>
using ThenResult =
std::enable_if_t<IsHandlerCallback<Callback, Args...>::value,
Result<RefPtr<Promise>, nsresult>>;
// Similar to the JavaScript then() function. Accepts two lambda function
// arguments, which it attaches as native resolve/reject handlers, and
// returns a new promise which:
// 1. if the ErrorResult contains an error value, rejects with it.
// 2. else, resolves with a return value.
//
// Any additional arguments passed after the callback functions are stored and
// passed as additional arguments to the functions when it is called. These
// values will participate in cycle collection for the promise handler, and
// therefore may safely form reference cycles with the promise chain.
//
// Any strong references required by the callbacks should be passed in this
// manner, rather than using lambda capture, lambda captures do not support
// cycle collection, and can easily lead to leaks.
template <typename ResolveCallback, typename RejectCallback, typename... Args>
ThenResult<ResolveCallback, Args...> ThenCatchWithCycleCollectedArgs(
ResolveCallback&& aOnResolve, RejectCallback&& aOnReject,
Args&&... aArgs);
// Same as ThenCatchWithCycleCollectedArgs, except the rejection error will
// simply be propagated.
template <typename Callback, typename... Args>
ThenResult<Callback, Args...> ThenWithCycleCollectedArgs(
Callback&& aOnResolve, Args&&... aArgs);
// Same as ThenCatchWithCycleCollectedArgs, except the resolved value will
// simply be propagated.
template <typename Callback, typename... Args>
ThenResult<Callback, Args...> CatchWithCycleCollectedArgs(
Callback&& aOnReject, Args&&... aArgs);
// Same as Then[Catch]CycleCollectedArgs but the arguments are gathered into
// an `std::tuple` and there is an additional `std::tuple` for JS arguments
// after that.
template <typename ResolveCallback, typename RejectCallback,
typename ArgsTuple, typename JSArgsTuple>
Result<RefPtr<Promise>, nsresult> ThenCatchWithCycleCollectedArgsJS(
ResolveCallback&& aOnResolve, RejectCallback&& aOnReject,
ArgsTuple&& aArgs, JSArgsTuple&& aJSArgs);
template <typename Callback, typename ArgsTuple, typename JSArgsTuple>
Result<RefPtr<Promise>, nsresult> ThenWithCycleCollectedArgsJS(
Callback&& aOnResolve, ArgsTuple&& aArgs, JSArgsTuple&& aJSArgs);
Result<RefPtr<Promise>, nsresult> ThenWithoutCycleCollection(
const std::function<already_AddRefed<Promise>(
JSContext*, JS::Handle<JS::Value>, ErrorResult& aRv)>& aCallback);
// Similar to ThenCatchWithCycleCollectedArgs but doesn't care with return
// values of the callbacks and does not return a new promise.
template <typename ResolveCallback, typename RejectCallback, typename... Args>
void AddCallbacksWithCycleCollectedArgs(ResolveCallback&& aOnResolve,
RejectCallback&& aOnReject,
Args&&... aArgs);
// This can be null if this promise is made after the corresponding JSContext
// is dead.
JSObject* PromiseObj() const { return mPromiseObj; }
void AppendNativeHandler(PromiseNativeHandler* aRunnable);
nsIGlobalObject* GetGlobalObject() const { return mGlobal; }
// Create a dom::Promise from a given SpiderMonkey Promise object.
// aPromiseObj MUST be in the compartment of aGlobal's global JS object.
// Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
// the promise resolve handler to be called as if we were handling user
// input events in case we are currently handling user input events.
static already_AddRefed<Promise> CreateFromExisting(
nsIGlobalObject* aGlobal, JS::Handle<JSObject*> aPromiseObj,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
enum class PromiseState { Pending, Resolved, Rejected };
PromiseState State() const;
static already_AddRefed<Promise> CreateResolvedWithUndefined(
nsIGlobalObject* aGlobal, ErrorResult& aRv);
static already_AddRefed<Promise> CreateRejected(
nsIGlobalObject* aGlobal, JS::Handle<JS::Value> aRejectionError,
ErrorResult& aRv);
static already_AddRefed<Promise> CreateRejectedWithTypeError(
nsIGlobalObject* aGlobal, const nsACString& aMessage, ErrorResult& aRv);
// The rejection error will be consumed if the promise is successfully
// created, else the error will remain and rv.Failed() will keep being true.
// This intentionally is not an overload of CreateRejected to prevent
// removing its third argument.)
static already_AddRefed<Promise> CreateRejectedWithErrorResult(
nsIGlobalObject* aGlobal, ErrorResult& aRejectionError);
// Converts an integer or DOMException to nsresult, or otherwise returns
// NS_ERROR_DOM_NOT_NUMBER_ERR (which is exclusive for this function).
// Can be used to convert JS::Value passed to rejection handler so that native
// error handlers e.g. MozPromise can consume it.
static nsresult TryExtractNSResultFromRejectionValue(
JS::Handle<JS::Value> aValue);
protected:
template <typename ResolveCallback, typename RejectCallback, typename... Args,
typename... JSArgs>
Result<RefPtr<Promise>, nsresult> ThenCatchWithCycleCollectedArgsJSImpl(
Maybe<ResolveCallback>&& aOnResolve, Maybe<RejectCallback>&& aOnReject,
std::tuple<Args...>&& aArgs, std::tuple<JSArgs...>&& aJSArgs);
template <typename ResolveCallback, typename RejectCallback, typename... Args>
ThenResult<ResolveCallback, Args...> ThenCatchWithCycleCollectedArgsImpl(
Maybe<ResolveCallback>&& aOnResolve, Maybe<RejectCallback>&& aOnReject,
Args&&... aArgs);
// Legacy method for throwing DOMExceptions. Only used by media code at this
// point, via DetailedPromise. Do NOT add new uses! When this is removed,
// remove the friend declaration in ErrorResult.h.
inline void MaybeRejectWithDOMException(nsresult rv,
const nsACString& aMessage) {
ErrorResult res;
res.ThrowDOMException(rv, aMessage);
MaybeReject(std::move(res));
}
struct PromiseCapability;
// Do NOT call this unless you're Promise::Create or
// Promise::CreateFromExisting. I wish we could enforce that from inside this
// class too, somehow.
explicit Promise(nsIGlobalObject* aGlobal);
virtual ~Promise();
// Do JS-wrapping after Promise creation.
// Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
// the promise resolve handler to be called as if we were handling user
// input events in case we are currently handling user input events.
// The error code can be:
// * NS_ERROR_UNEXPECTED when AutoJSAPI.Init fails
// * NS_ERROR_OUT_OF_MEMORY when NewPromiseObject throws OOM
// * NS_ERROR_NOT_INITIALIZED when NewPromiseObject fails without OOM
void CreateWrapper(ErrorResult& aRv,
PropagateUserInteraction aPropagateUserInteraction =
eDontPropagateUserInteraction);
private:
void MaybeResolve(JSContext* aCx, JS::Handle<JS::Value> aValue);
void MaybeReject(JSContext* aCx, JS::Handle<JS::Value> aValue);
template <typename T>
void MaybeSomething(T&& aArgument, MaybeFunc aFunc) {
if (NS_WARN_IF(!PromiseObj())) {
return;
}
AutoAllowLegacyScriptExecution exemption;
AutoEntryScript aes(mGlobal, "Promise resolution or rejection");
JSContext* cx = aes.cx();
JS::Rooted<JS::Value> val(cx);
if (!ToJSValue(cx, std::forward<T>(aArgument), &val)) {
HandleException(cx);
return;
}
(this->*aFunc)(cx, val);
}
void HandleException(JSContext* aCx);
bool MaybePropagateUserInputEventHandling();
RefPtr<nsIGlobalObject> mGlobal;
JS::Heap<JSObject*> mPromiseObj;
};
} // namespace mozilla::dom
extern "C" {
// These functions are used in the implementation of ffi bindings for
// dom::Promise from Rust in xpcom crate.
void DomPromise_AddRef(mozilla::dom::Promise* aPromise);
void DomPromise_Release(mozilla::dom::Promise* aPromise);
void DomPromise_RejectWithVariant(mozilla::dom::Promise* aPromise,
nsIVariant* aVariant);
void DomPromise_ResolveWithVariant(mozilla::dom::Promise* aPromise,
nsIVariant* aVariant);
}
#endif // mozilla_dom_Promise_h