diff options
Diffstat (limited to 'dom/bindings/ErrorResult.h')
| -rw-r--r-- | dom/bindings/ErrorResult.h | 928 |
1 files changed, 928 insertions, 0 deletions
diff --git a/dom/bindings/ErrorResult.h b/dom/bindings/ErrorResult.h new file mode 100644 index 0000000000..8b2f7e6164 --- /dev/null +++ b/dom/bindings/ErrorResult.h @@ -0,0 +1,928 @@ +/* -*- 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/. */ + +/** + * 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; + + 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(); + + // 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); + + // 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 { +namespace binding_detail { +class FastErrorResult : public mozilla::binding_danger::TErrorResult< + mozilla::binding_danger::JustAssertCleanupPolicy> { +}; +} // namespace binding_detail +} // namespace dom + +// 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 */ |