dom/base/JSExecutionContext.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef DOM_BASE_JSEXECUTIONCONTEXT_H_
   8 #define DOM_BASE_JSEXECUTIONCONTEXT_H_
   9
  10 #include "js/GCVector.h"
  11 #include "js/TypeDecls.h"
  12 #include "js/Value.h"
  13 #include "js/experimental/JSStencil.h"
  14 #include "jsapi.h"
  15 #include "mozilla/Assertions.h"
  16 #include "mozilla/Attributes.h"
  17 #include "mozilla/ProfilerLabels.h"
  18 #include "mozilla/Vector.h"
  19 #include "nsStringFwd.h"
  20 #include "nscore.h"
  21
  22 class nsIScriptContext;
  23 class nsIScriptElement;
  24 class nsIScriptGlobalObject;
  25 class nsXBLPrototypeBinding;
  26
  27 namespace mozilla {
  28 union Utf8Unit;
  29
  30 namespace dom {
  31
  32 class ScriptLoadContext;
  33
  34 class MOZ_STACK_CLASS JSExecutionContext final {
  35   // Register stack annotations for the Gecko profiler.
  36   mozilla::AutoProfilerLabel mAutoProfilerLabel;
  37
  38   JSContext* mCx;
  39
  40   // Handles switching to our global's realm.
  41   JSAutoRealm mRealm;
  42
  43   // Set to a valid handle if a return value is expected.
  44   JS::Rooted<JS::Value> mRetValue;
  45
  46   // The compiled script.
  47   JS::Rooted<JSScript*> mScript;
  48
  49   // The compilation options applied throughout
  50   JS::CompileOptions& mCompileOptions;
  51
  52   // Debug Metadata: Values managed for the benefit of the debugger when
  53   // inspecting code.
  54   //
  55   // For more details see CompilationAndEvaluation.h, and the comments on
  56   // UpdateDebugMetadata
  57   JS::Rooted<JS::Value> mDebuggerPrivateValue;
  58   JS::Rooted<JSScript*> mDebuggerIntroductionScript;
  59
  60   // returned value forwarded when we have to interupt the execution eagerly
  61   // with mSkip.
  62   nsresult mRv;
  63
  64   // Used to skip upcoming phases in case of a failure.  In such case the
  65   // result is carried by mRv.
  66   bool mSkip;
  67
  68   // Should the result be serialized before being returned.
  69   bool mCoerceToString;
  70
  71   // Encode the bytecode before it is being executed.
  72   bool mEncodeBytecode;
  73
  74 #ifdef DEBUG
  75   // Should we set the return value.
  76   bool mWantsReturnValue;
  77
  78   bool mScriptUsed;
  79 #endif
  80
  81  private:
  82   // Compile a script contained in a SourceText.
  83   template <typename Unit>
  84   nsresult InternalCompile(JS::SourceText<Unit>& aSrcBuf);
  85
  86   // Instantiate (on main-thread) a JS::Stencil generated by off-thread or
  87   // main-thread parsing or decoding.
  88   nsresult InstantiateStencil(RefPtr<JS::Stencil>&& aStencil,
  89                               JS::InstantiationStorage* aStorage = nullptr);
  90
  91  public:
  92   // Enter compartment in which the code would be executed.  The JSContext
  93   // must come from an AutoEntryScript.
  94   //
  95   // The JS engine can associate metadata for the debugger with scripts at
  96   // compile time. The optional last arguments here cover that metadata.
  97   JSExecutionContext(
  98       JSContext* aCx, JS::Handle<JSObject*> aGlobal,
  99       JS::CompileOptions& aCompileOptions,
 100       JS::Handle<JS::Value> aDebuggerPrivateValue = JS::UndefinedHandleValue,
 101       JS::Handle<JSScript*> aDebuggerIntroductionScript = nullptr);
 102
 103   JSExecutionContext(const JSExecutionContext&) = delete;
 104   JSExecutionContext(JSExecutionContext&&) = delete;
 105
 106   ~JSExecutionContext() {
 107     // This flag is reset when the returned value is extracted.
 108     MOZ_ASSERT_IF(!mSkip, !mWantsReturnValue);
 109
 110     // If encoding was started we expect the script to have been
 111     // used when ending the encoding.
 112     MOZ_ASSERT_IF(mEncodeBytecode && mScript && mRv == NS_OK, mScriptUsed);
 113   }
 114
 115   // The returned value would be converted to a string if the
 116   // |aCoerceToString| is flag set.
 117   JSExecutionContext& SetCoerceToString(bool aCoerceToString) {
 118     mCoerceToString = aCoerceToString;
 119     return *this;
 120   }
 121
 122   // When set, this flag records and encodes the bytecode as soon as it is
 123   // being compiled, and before it is being executed. The bytecode can then be
 124   // requested by using |JS::FinishIncrementalEncoding| with the mutable
 125   // handle |aScript| argument of |CompileAndExec| or |JoinAndExec|.
 126   JSExecutionContext& SetEncodeBytecode(bool aEncodeBytecode) {
 127     mEncodeBytecode = aEncodeBytecode;
 128     return *this;
 129   }
 130
 131   // After getting a notification that an off-thread compile/decode finished,
 132   // this function will take the result of the off-thread operation and move it
 133   // to the main thread.
 134   [[nodiscard]] nsresult JoinOffThread(ScriptLoadContext* aContext);
 135
 136   // Compile a script contained in a SourceText.
 137   nsresult Compile(JS::SourceText<char16_t>& aSrcBuf);
 138   nsresult Compile(JS::SourceText<mozilla::Utf8Unit>& aSrcBuf);
 139
 140   // Compile a script contained in a string.
 141   nsresult Compile(const nsAString& aScript);
 142
 143   // Decode a script contained in a buffer.
 144   nsresult Decode(const JS::TranscodeRange& aBytecodeBuf);
 145
 146   // Get a successfully compiled script.
 147   JSScript* GetScript();
 148
 149   // Get the compiled script if present, or nullptr.
 150   JSScript* MaybeGetScript();
 151
 152   // Execute the compiled script and ignore the return value.
 153   [[nodiscard]] nsresult ExecScript();
 154
 155   // Execute the compiled script a get the return value.
 156   //
 157   // Copy the returned value into the mutable handle argument. In case of a
 158   // evaluation failure either during the execution or the conversion of the
 159   // result to a string, the nsresult is be set to the corresponding result
 160   // code and the mutable handle argument remains unchanged.
 161   //
 162   // The value returned in the mutable handle argument is part of the
 163   // compartment given as argument to the JSExecutionContext constructor. If the
 164   // caller is in a different compartment, then the out-param value should be
 165   // wrapped by calling |JS_WrapValue|.
 166   [[nodiscard]] nsresult ExecScript(JS::MutableHandle<JS::Value> aRetValue);
 167 };
 168 }  // namespace dom
 169 }  // namespace mozilla
 170
 171 #endif /* DOM_BASE_JSEXECUTIONCONTEXT_H_ */