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,
/**
* A set of structs for tracking exceptions that need to be thrown to JS:
* ErrorResult and IgnoredErrorResult.
*
* Conceptually, these structs represent either success or an exception in the
* process of being thrown. This means that a failing ErrorResult _must_ be
* handled in one of the following ways before coming off the stack:
*
* 1) Suppressed via SuppressException().
* 2) Converted to a pure nsresult return value via StealNSResult().
* 3) Converted to an actual pending exception on a JSContext via
* MaybeSetPendingException.
* 4) Converted to an exception JS::Value (probably to then reject a Promise
* with) via dom::ToJSValue.
*
* An IgnoredErrorResult will automatically do the first of those four things.
*/
#ifndef mozilla_ErrorResult_h
#define mozilla_ErrorResult_h
#include <stdarg.h>
#include <new>
#include <utility>
#include "js/GCAnnotations.h"
#include "js/ErrorReport.h"
#include "js/Value.h"
#include "mozilla/Assertions.h"
#include "mozilla/Attributes.h"
#include "mozilla/Utf8.h"
#include "nsISupportsImpl.h"
#include "nsString.h"
#include "nsTArray.h"
#include "nscore.h"
namespace IPC {
class Message;
class MessageReader;
class MessageWriter;
template <typename>
struct ParamTraits;
} // namespace IPC
class PickleIterator;
namespace mozilla {
namespace dom {
class Promise;
enum ErrNum : uint16_t {
#define MSG_DEF(_name, _argc, _has_context, _exn, _str) _name,
#include "mozilla/dom/Errors.msg"
#undef MSG_DEF
Err_Limit
};
// Debug-only compile-time table of the number of arguments of each error, for
// use in static_assert.
#if defined(DEBUG) && (defined(__clang__) || defined(__GNUC__))
uint16_t constexpr ErrorFormatNumArgs[] = {
# define MSG_DEF(_name, _argc, _has_context, _exn, _str) _argc,
# include "mozilla/dom/Errors.msg"
# undef MSG_DEF
};
#endif
// Table of whether various error messages want a context arg.
bool constexpr ErrorFormatHasContext[] = {
#define MSG_DEF(_name, _argc, _has_context, _exn, _str) _has_context,
#include "mozilla/dom/Errors.msg"
#undef MSG_DEF
};
// Table of the kinds of exceptions error messages will produce.
JSExnType constexpr ErrorExceptionType[] = {
#define MSG_DEF(_name, _argc, _has_context, _exn, _str) _exn,
#include "mozilla/dom/Errors.msg"
#undef MSG_DEF
};
uint16_t GetErrorArgCount(const ErrNum aErrorNumber);
namespace binding_detail {
void ThrowErrorMessage(JSContext* aCx, const unsigned aErrorNumber, ...);
} // namespace binding_detail
template <ErrNum errorNumber, typename... Ts>
inline bool ThrowErrorMessage(JSContext* aCx, Ts&&... aArgs) {
#if defined(DEBUG) && (defined(__clang__) || defined(__GNUC__))
static_assert(ErrorFormatNumArgs[errorNumber] == sizeof...(aArgs),
"Pass in the right number of arguments");
#endif
binding_detail::ThrowErrorMessage(aCx, static_cast<unsigned>(errorNumber),
std::forward<Ts>(aArgs)...);
return false;
}
template <typename CharT>
struct TStringArrayAppender {
static void Append(nsTArray<nsTString<CharT>>& aArgs, uint16_t aCount) {
MOZ_RELEASE_ASSERT(aCount == 0,
"Must give at least as many string arguments as are "
"required by the ErrNum.");
}
// Allow passing nsAString/nsACString instances for our args.
template <typename... Ts>
static void Append(nsTArray<nsTString<CharT>>& aArgs, uint16_t aCount,
const nsTSubstring<CharT>& aFirst, Ts&&... aOtherArgs) {
if (aCount == 0) {
MOZ_ASSERT(false,
"There should not be more string arguments provided than are "
"required by the ErrNum.");
return;
}
aArgs.AppendElement(aFirst);
Append(aArgs, aCount - 1, std::forward<Ts>(aOtherArgs)...);
}
// Also allow passing literal instances for our args.
template <int N, typename... Ts>
static void Append(nsTArray<nsTString<CharT>>& aArgs, uint16_t aCount,
const CharT (&aFirst)[N], Ts&&... aOtherArgs) {
if (aCount == 0) {
MOZ_ASSERT(false,
"There should not be more string arguments provided than are "
"required by the ErrNum.");
return;
}
aArgs.AppendElement(nsTLiteralString<CharT>(aFirst));
Append(aArgs, aCount - 1, std::forward<Ts>(aOtherArgs)...);
}
};
using StringArrayAppender = TStringArrayAppender<char16_t>;
using CStringArrayAppender = TStringArrayAppender<char>;
} // namespace dom
class ErrorResult;
class OOMReporter;
class CopyableErrorResult;
namespace binding_danger {
/**
* Templated implementation class for various ErrorResult-like things. The
* instantiations differ only in terms of their cleanup policies (used in the
* destructor), which they can specify via the template argument. Note that
* this means it's safe to reinterpret_cast between the instantiations unless
* you plan to invoke the destructor through such a cast pointer.
*
* A cleanup policy consists of two booleans: whether to assert that we've been
* reported or suppressed, and whether to then go ahead and suppress the
* exception.
*/
template <typename CleanupPolicy>
class TErrorResult {
public:
TErrorResult()
: mResult(NS_OK)
#ifdef DEBUG
,
mMightHaveUnreportedJSException(false),
mUnionState(HasNothing)
#endif
{
}
~TErrorResult() {
AssertInOwningThread();
if (CleanupPolicy::assertHandled) {
// Consumers should have called one of MaybeSetPendingException
// (possibly via ToJSValue), StealNSResult, and SuppressException
AssertReportedOrSuppressed();
}
if (CleanupPolicy::suppress) {
SuppressException();
}
// And now assert that we're in a good final state.
AssertReportedOrSuppressed();
}
TErrorResult(TErrorResult&& aRHS)
// Initialize mResult and whatever else we need to default-initialize, so
// the ClearUnionData call in our operator= will do the right thing
// (nothing).
: TErrorResult() {
*this = std::move(aRHS);
}
TErrorResult& operator=(TErrorResult&& aRHS);
explicit TErrorResult(nsresult aRv) : TErrorResult() { AssignErrorCode(aRv); }
operator ErrorResult&();
operator const ErrorResult&() const;
operator OOMReporter&();
// This method is deprecated. Consumers should Throw*Error with the
// appropriate DOMException name if they are throwing a DOMException. If they
// have a random nsresult which may or may not correspond to a DOMException
// type, they should consider using an appropriate DOMException with an
// informative message and calling the relevant Throw*Error.
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG Throw(nsresult rv) {
MOZ_ASSERT(NS_FAILED(rv), "Please don't try throwing success");
AssignErrorCode(rv);
}
// Duplicate our current state on the given TErrorResult object. Any
// existing errors or messages on the target will be suppressed before
// cloning. Our own error state remains unchanged.
void CloneTo(TErrorResult& aRv) const;
// Use SuppressException when you want to suppress any exception that might be
// on the TErrorResult. After this call, the TErrorResult will be back a "no
// exception thrown" state.
void SuppressException();
// Use StealNSResult() when you want to safely convert the TErrorResult to
// an nsresult that you will then return to a caller. This will
// SuppressException(), since there will no longer be a way to report it.
nsresult StealNSResult() {
nsresult rv = ErrorCode();
SuppressException();
// Don't propagate out our internal error codes that have special meaning.
if (rv == NS_ERROR_INTERNAL_ERRORRESULT_TYPEERROR ||
rv == NS_ERROR_INTERNAL_ERRORRESULT_RANGEERROR ||
rv == NS_ERROR_INTERNAL_ERRORRESULT_JS_EXCEPTION ||
rv == NS_ERROR_INTERNAL_ERRORRESULT_DOMEXCEPTION) {
// What to pick here?
return NS_ERROR_DOM_INVALID_STATE_ERR;
}
return rv;
}
// Use MaybeSetPendingException to convert a TErrorResult to a pending
// exception on the given JSContext. This is the normal "throw an exception"
// codepath.
//
// The return value is false if the TErrorResult represents success, true
// otherwise. This does mean that in JSAPI method implementations you can't
// just use this as |return rv.MaybeSetPendingException(cx)| (though you could
// |return !rv.MaybeSetPendingException(cx)|), but in practice pretty much any
// consumer would want to do some more work on the success codepath. So
// instead the way you use this is:
//
// if (rv.MaybeSetPendingException(cx)) {
// bail out here
// }
// go on to do something useful
//
// The success path is inline, since it should be the common case and we don't
// want to pay the price of a function call in some of the consumers of this
// method in the common case.
//
// Note that a true return value does NOT mean there is now a pending
// exception on aCx, due to uncatchable exceptions. It should still be
// considered equivalent to a JSAPI failure in terms of what callers should do
// after true is returned.
//
// After this call, the TErrorResult will no longer return true from Failed(),
// since the exception will have moved to the JSContext.
//
// If "context" is not null and our exception has a useful message string, the
// string "%s: ", with the value of "context" replacing %s, will be prepended
// to the message string. The passed-in string must be ASCII.
[[nodiscard]] bool MaybeSetPendingException(
JSContext* cx, const char* description = nullptr) {
WouldReportJSException();
if (!Failed()) {
return false;
}
SetPendingException(cx, description);
return true;
}
// Use StealExceptionFromJSContext to convert a pending exception on a
// JSContext to a TErrorResult. This function must be called only when a
// JSAPI operation failed. It assumes that lack of pending exception on the
// JSContext means an uncatchable exception was thrown.
//
// Codepaths that might call this method must call MightThrowJSException even
// if the relevant JSAPI calls do not fail.
//
// When this function returns, JS_IsExceptionPending(cx) will definitely be
// false.
void StealExceptionFromJSContext(JSContext* cx);
template <dom::ErrNum errorNumber, typename... Ts>
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowTypeError(Ts&&... messageArgs) {
static_assert(dom::ErrorExceptionType[errorNumber] == JSEXN_TYPEERR,
"Throwing a non-TypeError via ThrowTypeError");
ThrowErrorWithMessage<errorNumber>(NS_ERROR_INTERNAL_ERRORRESULT_TYPEERROR,
std::forward<Ts>(messageArgs)...);
}
// To be used when throwing a TypeError with a completely custom
// message string that's only used in one spot.
inline void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowTypeError(const nsACString& aMessage) {
this->template ThrowTypeError<dom::MSG_ONE_OFF_TYPEERR>(aMessage);
}
// To be used when throwing a TypeError with a completely custom
// message string that's a string literal that's only used in one spot.
template <int N>
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowTypeError(const char (&aMessage)[N]) {
ThrowTypeError(nsLiteralCString(aMessage));
}
template <dom::ErrNum errorNumber, typename... Ts>
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowRangeError(Ts&&... messageArgs) {
static_assert(dom::ErrorExceptionType[errorNumber] == JSEXN_RANGEERR,
"Throwing a non-RangeError via ThrowRangeError");
ThrowErrorWithMessage<errorNumber>(NS_ERROR_INTERNAL_ERRORRESULT_RANGEERROR,
std::forward<Ts>(messageArgs)...);
}
// To be used when throwing a RangeError with a completely custom
// message string that's only used in one spot.
inline void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowRangeError(const nsACString& aMessage) {
this->template ThrowRangeError<dom::MSG_ONE_OFF_RANGEERR>(aMessage);
}
// To be used when throwing a RangeError with a completely custom
// message string that's a string literal that's only used in one spot.
template <int N>
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowRangeError(const char (&aMessage)[N]) {
ThrowRangeError(nsLiteralCString(aMessage));
}
bool IsErrorWithMessage() const {
return ErrorCode() == NS_ERROR_INTERNAL_ERRORRESULT_TYPEERROR ||
ErrorCode() == NS_ERROR_INTERNAL_ERRORRESULT_RANGEERROR;
}
// Facilities for throwing a preexisting JS exception value via this
// TErrorResult. The contract is that any code which might end up calling
// ThrowJSException() or StealExceptionFromJSContext() must call
// MightThrowJSException() even if no exception is being thrown. Code that
// conditionally calls ToJSValue on this TErrorResult only if Failed() must
// first call WouldReportJSException even if this TErrorResult has not failed.
//
// The exn argument to ThrowJSException can be in any compartment. It does
// not have to be in the compartment of cx. If someone later uses it, they
// will wrap it into whatever compartment they're working in, as needed.
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowJSException(JSContext* cx, JS::Handle<JS::Value> exn);
bool IsJSException() const {
return ErrorCode() == NS_ERROR_INTERNAL_ERRORRESULT_JS_EXCEPTION;
}
// Facilities for throwing DOMExceptions of whatever type a spec calls for.
// If an empty message string is passed to one of these Throw*Error functions,
// the default message string for the relevant type of DOMException will be
// used. The passed-in string must be UTF-8.
#define DOMEXCEPTION(name, err) \
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG Throw##name( \
const nsACString& aMessage) { \
ThrowDOMException(err, aMessage); \
} \
\
template <int N> \
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG Throw##name( \
const char(&aMessage)[N]) { \
ThrowDOMException(err, aMessage); \
}
#include "mozilla/dom/DOMExceptionNames.h"
#undef DOMEXCEPTION
bool IsDOMException() const {
return ErrorCode() == NS_ERROR_INTERNAL_ERRORRESULT_DOMEXCEPTION;
}
// Flag on the TErrorResult that whatever needs throwing has been
// thrown on the JSContext already and we should not mess with it.
// If nothing was thrown, this becomes an uncatchable exception.
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
NoteJSContextException(JSContext* aCx);
// Check whether the TErrorResult says to just throw whatever is on
// the JSContext already.
bool IsJSContextException() {
return ErrorCode() == NS_ERROR_INTERNAL_ERRORRESULT_EXCEPTION_ON_JSCONTEXT;
}
// Support for uncatchable exceptions.
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG ThrowUncatchableException() {
Throw(NS_ERROR_UNCATCHABLE_EXCEPTION);
}
bool IsUncatchableException() const {
return ErrorCode() == NS_ERROR_UNCATCHABLE_EXCEPTION;
}
void MOZ_ALWAYS_INLINE MightThrowJSException() {
#ifdef DEBUG
mMightHaveUnreportedJSException = true;
#endif
}
void MOZ_ALWAYS_INLINE WouldReportJSException() {
#ifdef DEBUG
mMightHaveUnreportedJSException = false;
#endif
}
// In the future, we can add overloads of Throw that take more
// interesting things, like strings or DOM exception types or
// something if desired.
// Backwards-compat to make conversion simpler. We don't call
// Throw() here because people can easily pass success codes to
// this. This operator is deprecated and ideally shouldn't be used.
void operator=(nsresult rv) { AssignErrorCode(rv); }
bool Failed() const { return NS_FAILED(mResult); }
bool ErrorCodeIs(nsresult rv) const { return mResult == rv; }
// For use in logging ONLY.
uint32_t ErrorCodeAsInt() const { return static_cast<uint32_t>(ErrorCode()); }
bool operator==(const ErrorResult& aRight) const;
protected:
nsresult ErrorCode() const { return mResult; }
// Helper methods for throwing DOMExceptions, for now. We can try to get rid
// of these once EME code is fixed to not use them and we decouple
// DOMExceptions from nsresult.
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowDOMException(nsresult rv, const nsACString& message);
// Same thing, but using a string literal.
template <int N>
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG
ThrowDOMException(nsresult rv, const char (&aMessage)[N]) {
ThrowDOMException(rv, nsLiteralCString(aMessage));
}
// Allow Promise to call the above methods when it really needs to.
// Unfortunately, we can't have the definition of Promise here, so can't mark
// just it's MaybeRejectWithDOMException method as a friend. In any case,
// hopefully it's all temporary until we sort out the EME bits.
friend class dom::Promise;
// Implementation of MaybeSetPendingException for the case when we're a
// failure result. See documentation of MaybeSetPendingException for the
// "context" argument.
void SetPendingException(JSContext* cx, const char* context);
private:
#ifdef DEBUG
enum UnionState {
HasMessage,
HasDOMExceptionInfo,
HasJSException,
HasNothing
};
#endif // DEBUG
friend struct IPC::ParamTraits<TErrorResult>;
friend struct IPC::ParamTraits<ErrorResult>;
void SerializeMessage(IPC::MessageWriter* aWriter) const;
bool DeserializeMessage(IPC::MessageReader* aReader);
void SerializeDOMExceptionInfo(IPC::MessageWriter* aWriter) const;
bool DeserializeDOMExceptionInfo(IPC::MessageReader* aReader);
// Helper method that creates a new Message for this TErrorResult,
// and returns the arguments array from that Message.
nsTArray<nsCString>& CreateErrorMessageHelper(const dom::ErrNum errorNumber,
nsresult errorType);
// Helper method to replace invalid UTF-8 characters with the replacement
// character. aValidUpTo is the number of characters that are known to be
// valid. The string might be truncated if we encounter an OOM error.
static void EnsureUTF8Validity(nsCString& aValue, size_t aValidUpTo);
template <dom::ErrNum errorNumber, typename... Ts>
void ThrowErrorWithMessage(nsresult errorType, Ts&&... messageArgs) {
#if defined(DEBUG) && (defined(__clang__) || defined(__GNUC__))
static_assert(dom::ErrorFormatNumArgs[errorNumber] ==
sizeof...(messageArgs) +
int(dom::ErrorFormatHasContext[errorNumber]),
"Pass in the right number of arguments");
#endif
ClearUnionData();
nsTArray<nsCString>& messageArgsArray =
CreateErrorMessageHelper(errorNumber, errorType);
uint16_t argCount = dom::GetErrorArgCount(errorNumber);
if (dom::ErrorFormatHasContext[errorNumber]) {
// Insert an empty string arg at the beginning and reduce our arg count to
// still be appended accordingly.
MOZ_ASSERT(argCount > 0,
"Must have at least one arg if we have a context!");
MOZ_ASSERT(messageArgsArray.Length() == 0,
"Why do we already have entries in the array?");
--argCount;
messageArgsArray.AppendElement();
}
dom::CStringArrayAppender::Append(messageArgsArray, argCount,
std::forward<Ts>(messageArgs)...);
for (nsCString& arg : messageArgsArray) {
size_t validUpTo = Utf8ValidUpTo(arg);
if (validUpTo != arg.Length()) {
EnsureUTF8Validity(arg, validUpTo);
}
}
#ifdef DEBUG
mUnionState = HasMessage;
#endif // DEBUG
}
MOZ_ALWAYS_INLINE void AssertInOwningThread() const {
#ifdef DEBUG
if (CleanupPolicy::assertSameThread) {
NS_ASSERT_OWNINGTHREAD(TErrorResult);
}
#endif
}
void AssignErrorCode(nsresult aRv) {
MOZ_ASSERT(aRv != NS_ERROR_INTERNAL_ERRORRESULT_TYPEERROR,
"Use ThrowTypeError()");
MOZ_ASSERT(aRv != NS_ERROR_INTERNAL_ERRORRESULT_RANGEERROR,
"Use ThrowRangeError()");
MOZ_ASSERT(!IsErrorWithMessage(), "Don't overwrite errors with message");
MOZ_ASSERT(aRv != NS_ERROR_INTERNAL_ERRORRESULT_JS_EXCEPTION,
"Use ThrowJSException()");
MOZ_ASSERT(!IsJSException(), "Don't overwrite JS exceptions");
MOZ_ASSERT(aRv != NS_ERROR_INTERNAL_ERRORRESULT_DOMEXCEPTION,
"Use Throw*Error for the appropriate DOMException name");
MOZ_ASSERT(!IsDOMException(), "Don't overwrite DOM exceptions");
MOZ_ASSERT(aRv != NS_ERROR_XPC_NOT_ENOUGH_ARGS,
"May need to bring back ThrowNotEnoughArgsError");
MOZ_ASSERT(aRv != NS_ERROR_INTERNAL_ERRORRESULT_EXCEPTION_ON_JSCONTEXT,
"Use NoteJSContextException");
mResult = aRv;
}
void ClearMessage();
void ClearDOMExceptionInfo();
// ClearUnionData will try to clear the data in our mExtra union. After this
// the union may be in an uninitialized state (e.g. mMessage or
// mDOMExceptionInfo may point to deleted memory, or mJSException may be a
// JS::Value containing an invalid gcthing) and the caller must either
// reinitialize it or change mResult to something that will not involve us
// touching the union anymore.
void ClearUnionData();
// Methods for setting various specific kinds of pending exceptions. See
// documentation of MaybeSetPendingException for the "context" argument.
void SetPendingExceptionWithMessage(JSContext* cx, const char* context);
void SetPendingJSException(JSContext* cx);
void SetPendingDOMException(JSContext* cx, const char* context);
void SetPendingGenericErrorException(JSContext* cx);
MOZ_ALWAYS_INLINE void AssertReportedOrSuppressed() {
MOZ_ASSERT(!Failed());
MOZ_ASSERT(!mMightHaveUnreportedJSException);
MOZ_ASSERT(mUnionState == HasNothing);
}
// Special values of mResult:
// NS_ERROR_INTERNAL_ERRORRESULT_TYPEERROR -- ThrowTypeError() called on us.
// NS_ERROR_INTERNAL_ERRORRESULT_RANGEERROR -- ThrowRangeError() called on us.
// NS_ERROR_INTERNAL_ERRORRESULT_JS_EXCEPTION -- ThrowJSException() called
// on us.
// NS_ERROR_UNCATCHABLE_EXCEPTION -- ThrowUncatchableException called on us.
// NS_ERROR_INTERNAL_ERRORRESULT_DOMEXCEPTION -- ThrowDOMException() called
// on us.
nsresult mResult;
struct Message;
struct DOMExceptionInfo;
union Extra {
// mMessage is set by ThrowErrorWithMessage and reported (and deallocated)
// by SetPendingExceptionWithMessage.
MOZ_INIT_OUTSIDE_CTOR
Message* mMessage; // valid when IsErrorWithMessage()
// mJSException is set (and rooted) by ThrowJSException and reported (and
// unrooted) by SetPendingJSException.
MOZ_INIT_OUTSIDE_CTOR
JS::Value mJSException; // valid when IsJSException()
// mDOMExceptionInfo is set by ThrowDOMException and reported (and
// deallocated) by SetPendingDOMException.
MOZ_INIT_OUTSIDE_CTOR
DOMExceptionInfo* mDOMExceptionInfo; // valid when IsDOMException()
// |mJSException| has a non-trivial constructor and therefore MUST be
// placement-new'd into existence.
MOZ_PUSH_DISABLE_NONTRIVIAL_UNION_WARNINGS
Extra() {} // NOLINT
MOZ_POP_DISABLE_NONTRIVIAL_UNION_WARNINGS
} mExtra;
Message* InitMessage(Message* aMessage) {
// The |new| here switches the active arm of |mExtra|, from the compiler's
// point of view. Mere assignment *won't* necessarily do the right thing!
new (&mExtra.mMessage) Message*(aMessage);
return mExtra.mMessage;
}
JS::Value& InitJSException() {
// The |new| here switches the active arm of |mExtra|, from the compiler's
// point of view. Mere assignment *won't* necessarily do the right thing!
new (&mExtra.mJSException) JS::Value(); // sets to undefined
return mExtra.mJSException;
}
DOMExceptionInfo* InitDOMExceptionInfo(DOMExceptionInfo* aDOMExceptionInfo) {
// The |new| here switches the active arm of |mExtra|, from the compiler's
// point of view. Mere assignment *won't* necessarily do the right thing!
new (&mExtra.mDOMExceptionInfo) DOMExceptionInfo*(aDOMExceptionInfo);
return mExtra.mDOMExceptionInfo;
}
#ifdef DEBUG
// Used to keep track of codepaths that might throw JS exceptions,
// for assertion purposes.
bool mMightHaveUnreportedJSException;
// Used to keep track of what's stored in our union right now. Note
// that this may be set to HasNothing even if our mResult suggests
// we should have something, if we have already cleaned up the
// something.
UnionState mUnionState;
// The thread that created this TErrorResult
NS_DECL_OWNINGTHREAD;
#endif
// Not to be implemented, to make sure people always pass this by
// reference, not by value.
TErrorResult(const TErrorResult&) = delete;
void operator=(const TErrorResult&) = delete;
} JS_HAZ_ROOTED;
struct JustAssertCleanupPolicy {
static const bool assertHandled = true;
static const bool suppress = false;
static const bool assertSameThread = true;
};
struct AssertAndSuppressCleanupPolicy {
static const bool assertHandled = true;
static const bool suppress = true;
static const bool assertSameThread = true;
};
struct JustSuppressCleanupPolicy {
static const bool assertHandled = false;
static const bool suppress = true;
static const bool assertSameThread = true;
};
struct ThreadSafeJustSuppressCleanupPolicy {
static const bool assertHandled = false;
static const bool suppress = true;
static const bool assertSameThread = false;
};
} // namespace binding_danger
// A class people should normally use on the stack when they plan to actually
// do something with the exception.
class ErrorResult : public binding_danger::TErrorResult<
binding_danger::AssertAndSuppressCleanupPolicy> {
typedef binding_danger::TErrorResult<
binding_danger::AssertAndSuppressCleanupPolicy>
BaseErrorResult;
public:
ErrorResult() = default;
ErrorResult(ErrorResult&& aRHS) = default;
// Explicitly allow moving out of a CopyableErrorResult into an ErrorResult.
// This is implemented below so it can see the definition of
// CopyableErrorResult.
inline explicit ErrorResult(CopyableErrorResult&& aRHS);
explicit ErrorResult(nsresult aRv) : BaseErrorResult(aRv) {}
// This operator is deprecated and ideally shouldn't be used.
void operator=(nsresult rv) { BaseErrorResult::operator=(rv); }
ErrorResult& operator=(ErrorResult&& aRHS) = default;
// Not to be implemented, to make sure people always pass this by
// reference, not by value.
ErrorResult(const ErrorResult&) = delete;
ErrorResult& operator=(const ErrorResult&) = delete;
};
template <typename CleanupPolicy>
binding_danger::TErrorResult<CleanupPolicy>::operator ErrorResult&() {
return *static_cast<ErrorResult*>(
reinterpret_cast<TErrorResult<AssertAndSuppressCleanupPolicy>*>(this));
}
template <typename CleanupPolicy>
binding_danger::TErrorResult<CleanupPolicy>::operator const ErrorResult&()
const {
return *static_cast<const ErrorResult*>(
reinterpret_cast<const TErrorResult<AssertAndSuppressCleanupPolicy>*>(
this));
}
// A class for use when an ErrorResult should just automatically be ignored.
// This doesn't inherit from ErrorResult so we don't make two separate calls to
// SuppressException.
class IgnoredErrorResult : public binding_danger::TErrorResult<
binding_danger::JustSuppressCleanupPolicy> {};
// A class for use when an ErrorResult needs to be copied to a lambda, into
// an IPDL structure, etc. Since this will often involve crossing thread
// boundaries this class will assert if you try to copy a JS exception. Only
// use this if you are propagating internal errors. In general its best
// to use ErrorResult by default and only convert to a CopyableErrorResult when
// you need it.
class CopyableErrorResult
: public binding_danger::TErrorResult<
binding_danger::ThreadSafeJustSuppressCleanupPolicy> {
typedef binding_danger::TErrorResult<
binding_danger::ThreadSafeJustSuppressCleanupPolicy>
BaseErrorResult;
public:
CopyableErrorResult() = default;
explicit CopyableErrorResult(const ErrorResult& aRight) : BaseErrorResult() {
auto val = reinterpret_cast<const CopyableErrorResult&>(aRight);
operator=(val);
}
CopyableErrorResult(CopyableErrorResult&& aRHS) = default;
explicit CopyableErrorResult(ErrorResult&& aRHS) : BaseErrorResult() {
// We must not copy JS exceptions since it can too easily lead to
// off-thread use. Assert this and fall back to a generic error
// in release builds.
MOZ_DIAGNOSTIC_ASSERT(
!aRHS.IsJSException(),
"Attempt to copy from ErrorResult with a JS exception value.");
if (aRHS.IsJSException()) {
aRHS.SuppressException();
Throw(NS_ERROR_FAILURE);
} else {
// We could avoid the cast here if we had a move constructor on
// TErrorResult templated on the cleanup policy type, but then we'd have
// to either inline the impl or force all possible instantiations or
// something. This is a bit simpler, and not that different from our copy
// constructor.
auto val = reinterpret_cast<CopyableErrorResult&&>(aRHS);
operator=(val);
}
}
explicit CopyableErrorResult(nsresult aRv) : BaseErrorResult(aRv) {}
// This operator is deprecated and ideally shouldn't be used.
void operator=(nsresult rv) { BaseErrorResult::operator=(rv); }
CopyableErrorResult& operator=(CopyableErrorResult&& aRHS) = default;
CopyableErrorResult(const CopyableErrorResult& aRight) : BaseErrorResult() {
operator=(aRight);
}
CopyableErrorResult& operator=(const CopyableErrorResult& aRight) {
// We must not copy JS exceptions since it can too easily lead to
// off-thread use. Assert this and fall back to a generic error
// in release builds.
MOZ_DIAGNOSTIC_ASSERT(
!IsJSException(),
"Attempt to copy to ErrorResult with a JS exception value.");
MOZ_DIAGNOSTIC_ASSERT(
!aRight.IsJSException(),
"Attempt to copy from ErrorResult with a JS exception value.");
if (aRight.IsJSException()) {
SuppressException();
Throw(NS_ERROR_FAILURE);
} else {
aRight.CloneTo(*this);
}
return *this;
}
// Disallow implicit converstion to non-const ErrorResult&, because that would
// allow people to throw exceptions on us while bypassing our checks for JS
// exceptions.
operator ErrorResult&() = delete;
// Allow conversion to ErrorResult&& so we can move out of ourselves into
// an ErrorResult.
operator ErrorResult&&() && {
auto* val = reinterpret_cast<ErrorResult*>(this);
return std::move(*val);
}
};
inline ErrorResult::ErrorResult(CopyableErrorResult&& aRHS)
: ErrorResult(reinterpret_cast<ErrorResult&&>(aRHS)) {}
namespace dom::binding_detail {
enum class ErrorFor {
getter,
setter,
};
template <ErrorFor ErrorType>
struct ErrorDescriptionFor {
const char* mInterface;
const char* mMember;
};
class FastErrorResult : public mozilla::binding_danger::TErrorResult<
mozilla::binding_danger::JustAssertCleanupPolicy> {
public:
using TErrorResult::MaybeSetPendingException;
template <ErrorFor ErrorType>
[[nodiscard]] bool MaybeSetPendingException(
JSContext* aCx, const ErrorDescriptionFor<ErrorType>& aDescription) {
WouldReportJSException();
if (!Failed()) {
return false;
}
nsAutoCString description(aDescription.mInterface);
description.Append('.');
description.Append(aDescription.mMember);
if constexpr (ErrorType == ErrorFor::getter) {
description.AppendLiteral(" getter");
} else {
static_assert(ErrorType == ErrorFor::setter);
description.AppendLiteral(" setter");
}
SetPendingException(aCx, description.get());
return true;
}
};
} // namespace dom::binding_detail
// We want an OOMReporter class that has the following properties:
//
// 1) Can be cast to from any ErrorResult-like type.
// 2) Has a fast destructor (because we want to use it from bindings).
// 3) Won't be randomly instantiated by non-binding code (because the fast
// destructor is not so safe).
// 4) Doesn't look ugly on the callee side (e.g. isn't in the binding_detail or
// binding_danger namespace).
//
// We do this by creating a class that can't actually be constructed directly
// but can be cast to from ErrorResult-like types, both implicitly and
// explicitly.
class OOMReporter : private dom::binding_detail::FastErrorResult {
public:
void MOZ_MUST_RETURN_FROM_CALLER_IF_THIS_IS_ARG ReportOOM() {
Throw(NS_ERROR_OUT_OF_MEMORY);
}
// A method that turns a FastErrorResult into an OOMReporter, which we use in
// codegen to ensure that callees don't take an ErrorResult when they should
// only be taking an OOMReporter. The idea is that we can then just have a
// FastErrorResult on the stack and call this to produce the thing to pass to
// callees.
static OOMReporter& From(FastErrorResult& aRv) { return aRv; }
private:
// TErrorResult is a friend so its |operator OOMReporter&()| can work.
template <typename CleanupPolicy>
friend class binding_danger::TErrorResult;
OOMReporter() : dom::binding_detail::FastErrorResult() {}
};
template <typename CleanupPolicy>
binding_danger::TErrorResult<CleanupPolicy>::operator OOMReporter&() {
return *static_cast<OOMReporter*>(
reinterpret_cast<TErrorResult<JustAssertCleanupPolicy>*>(this));
}
// A class for use when an ErrorResult should just automatically be
// ignored. This is designed to be passed as a temporary only, like
// so:
//
// foo->Bar(IgnoreErrors());
class MOZ_TEMPORARY_CLASS IgnoreErrors {
public:
operator ErrorResult&() && { return mInner; }
operator OOMReporter&() && { return mInner; }
private:
// We don't use an ErrorResult member here so we don't make two separate calls
// to SuppressException (one from us, one from the ErrorResult destructor
// after asserting).
binding_danger::TErrorResult<binding_danger::JustSuppressCleanupPolicy>
mInner;
} JS_HAZ_ROOTED;
/******************************************************************************
** Macros for checking results
******************************************************************************/
#define ENSURE_SUCCESS(res, ret) \
do { \
if (res.Failed()) { \
nsCString msg; \
msg.AppendPrintf( \
"ENSURE_SUCCESS(%s, %s) failed with " \
"result 0x%X", \
#res, #ret, res.ErrorCodeAsInt()); \
NS_WARNING(msg.get()); \
return ret; \
} \
} while (0)
#define ENSURE_SUCCESS_VOID(res) \
do { \
if (res.Failed()) { \
nsCString msg; \
msg.AppendPrintf( \
"ENSURE_SUCCESS_VOID(%s) failed with " \
"result 0x%X", \
#res, res.ErrorCodeAsInt()); \
NS_WARNING(msg.get()); \
return; \
} \
} while (0)
} // namespace mozilla
#endif /* mozilla_ErrorResult_h */