libraries/source/spidermonkey/include-win32-debug/js/Transcoding.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * Structures and functions for transcoding compiled scripts and functions to
   8  * and from memory.
   9  */
  10
  11 #ifndef js_Transcoding_h
  12 #define js_Transcoding_h
  13
  14 #include "mozilla/Range.h"   // mozilla::Range
  15 #include "mozilla/Vector.h"  // mozilla::Vector
  16
  17 #include <stddef.h>  // size_t
  18 #include <stdint.h>  // uint8_t, uint32_t
  19
  20 #include "js/TypeDecls.h"
  21
  22 namespace JS {
  23
  24 class ReadOnlyCompileOptions;
  25
  26 using TranscodeBuffer = mozilla::Vector<uint8_t>;
  27 using TranscodeRange = mozilla::Range<const uint8_t>;
  28
  29 struct TranscodeSource final {
  30   TranscodeSource(const TranscodeRange& range_, const char* file, uint32_t line)
  31       : range(range_), filename(file), lineno(line) {}
  32
  33   const TranscodeRange range;
  34   const char* filename;
  35   const uint32_t lineno;
  36 };
  37
  38 using TranscodeSources = mozilla::Vector<TranscodeSource>;
  39
  40 enum class TranscodeResult : uint8_t {
  41   // Successful encoding / decoding.
  42   Ok = 0,
  43
  44   // A warning message, is set to the message out-param.
  45   Failure = 0x10,
  46   Failure_BadBuildId = Failure | 0x1,
  47   Failure_RunOnceNotSupported = Failure | 0x2,
  48   Failure_AsmJSNotSupported = Failure | 0x3,
  49   Failure_BadDecode = Failure | 0x4,
  50   Failure_WrongCompileOption = Failure | 0x5,
  51   Failure_NotInterpretedFun = Failure | 0x6,
  52
  53   // There is a pending exception on the context.
  54   Throw = 0x20
  55 };
  56
  57 inline bool IsTranscodeFailureResult(const TranscodeResult result) {
  58   uint8_t raw_result = static_cast<uint8_t>(result);
  59   uint8_t raw_failure = static_cast<uint8_t>(TranscodeResult::Failure);
  60   TranscodeResult masked =
  61       static_cast<TranscodeResult>(raw_result & raw_failure);
  62   return masked == TranscodeResult::Failure;
  63 }
  64
  65 static constexpr size_t BytecodeOffsetAlignment = 4;
  66 static_assert(BytecodeOffsetAlignment <= alignof(std::max_align_t),
  67               "Alignment condition requires a custom allocator.");
  68
  69 // Align the bytecode offset for transcoding for the requirement.
  70 inline size_t AlignTranscodingBytecodeOffset(size_t offset) {
  71   size_t extra = offset % BytecodeOffsetAlignment;
  72   if (extra == 0) {
  73     return offset;
  74   }
  75   size_t padding = BytecodeOffsetAlignment - extra;
  76   return offset + padding;
  77 }
  78
  79 inline bool IsTranscodingBytecodeOffsetAligned(size_t offset) {
  80   return offset % BytecodeOffsetAlignment == 0;
  81 }
  82
  83 inline bool IsTranscodingBytecodeAligned(const void* offset) {
  84   return IsTranscodingBytecodeOffsetAligned(size_t(offset));
  85 }
  86
  87 // Encode JSScript into the buffer.
  88 //
  89 // If the `buffer` isn't empty, the start of the `buffer` should meet
  90 // IsTranscodingBytecodeAligned, and the length should meet
  91 // IsTranscodingBytecodeOffsetAligned.
  92 //
  93 // NOTE: As long as IsTranscodingBytecodeOffsetAligned is met, that means
  94 //       there's JS::BytecodeOffsetAlignment+extra bytes in the buffer,
  95 //       IsTranscodingBytecodeAligned should be guaranteed to meet by
  96 //       malloc, used by MallocAllocPolicy in mozilla::Vector.
  97 extern JS_PUBLIC_API TranscodeResult EncodeScript(JSContext* cx,
  98                                                   TranscodeBuffer& buffer,
  99                                                   Handle<JSScript*> script);
 100
 101 // Decode JSScript from the buffer.
 102 //
 103 // The start of `buffer` and `cursorIndex` should meet
 104 // IsTranscodingBytecodeAligned and IsTranscodingBytecodeOffsetAligned.
 105 // (This should be handled while encoding).
 106 extern JS_PUBLIC_API TranscodeResult
 107 DecodeScript(JSContext* cx, const ReadOnlyCompileOptions& options,
 108              TranscodeBuffer& buffer, MutableHandle<JSScript*> scriptp,
 109              size_t cursorIndex = 0);
 110
 111 // Decode JSScript from the range.
 112 //
 113 // The start of `range` should meet IsTranscodingBytecodeAligned and
 114 // IsTranscodingBytecodeOffsetAligned.
 115 // (This should be handled while encoding).
 116 extern JS_PUBLIC_API TranscodeResult
 117 DecodeScript(JSContext* cx, const ReadOnlyCompileOptions& options,
 118              const TranscodeRange& range, MutableHandle<JSScript*> scriptp);
 119
 120 // If js::UseOffThreadParseGlobal is true, decode JSScript from the buffer.
 121 //
 122 // If js::UseOffThreadParseGlobal is false, decode CompilationStencil from the
 123 // buffer and instantiate JSScript from it.
 124 //
 125 // options.useOffThreadParseGlobal should match JS::SetUseOffThreadParseGlobal.
 126 //
 127 // The start of `buffer` and `cursorIndex` should meet
 128 // IsTranscodingBytecodeAligned and IsTranscodingBytecodeOffsetAligned.
 129 // (This should be handled while encoding).
 130 extern JS_PUBLIC_API TranscodeResult DecodeScriptMaybeStencil(
 131     JSContext* cx, const ReadOnlyCompileOptions& options,
 132     TranscodeBuffer& buffer, MutableHandle<JSScript*> scriptp,
 133     size_t cursorIndex = 0);
 134
 135 // If js::UseOffThreadParseGlobal is true, decode JSScript from the buffer.
 136 //
 137 // If js::UseOffThreadParseGlobal is false, decode CompilationStencil from the
 138 // buffer and instantiate JSScript from it.
 139 //
 140 // And then register an encoder on its script source, such that all functions
 141 // can be encoded as they are parsed. This strategy is used to avoid blocking
 142 // the main thread in a non-interruptible way.
 143 //
 144 // See also JS::FinishIncrementalEncoding.
 145 //
 146 // options.useOffThreadParseGlobal should match JS::SetUseOffThreadParseGlobal.
 147 //
 148 // The start of `buffer` and `cursorIndex` should meet
 149 // IsTranscodingBytecodeAligned and IsTranscodingBytecodeOffsetAligned.
 150 // (This should be handled while encoding).
 151 extern JS_PUBLIC_API TranscodeResult DecodeScriptAndStartIncrementalEncoding(
 152     JSContext* cx, const ReadOnlyCompileOptions& options,
 153     TranscodeBuffer& buffer, MutableHandle<JSScript*> scriptp,
 154     size_t cursorIndex = 0);
 155
 156 // Finish incremental encoding started by one of:
 157 //   * JS::CompileAndStartIncrementalEncoding
 158 //   * JS::FinishOffThreadScriptAndStartIncrementalEncoding
 159 //   * JS::DecodeScriptAndStartIncrementalEncoding
 160 //
 161 // The |script| argument of |FinishIncrementalEncoding| should be the top-level
 162 // script returned from one of the above.
 163 //
 164 // The |buffer| argument of |FinishIncrementalEncoding| is used for appending
 165 // the encoded bytecode into the buffer. If any of these functions failed, the
 166 // content of |buffer| would be undefined.
 167 //
 168 // If js::UseOffThreadParseGlobal is true, |buffer| contains encoded JSScript.
 169 //
 170 // If js::UseOffThreadParseGlobal is false, |buffer| contains encoded
 171 // CompilationStencil.
 172 //
 173 // If the `buffer` isn't empty, the start of the `buffer` should meet
 174 // IsTranscodingBytecodeAligned, and the length should meet
 175 // IsTranscodingBytecodeOffsetAligned.
 176 //
 177 // NOTE: As long as IsTranscodingBytecodeOffsetAligned is met, that means
 178 //       there's JS::BytecodeOffsetAlignment+extra bytes in the buffer,
 179 //       IsTranscodingBytecodeAligned should be guaranteed to meet by
 180 //       malloc, used by MallocAllocPolicy in mozilla::Vector.
 181 extern JS_PUBLIC_API bool FinishIncrementalEncoding(JSContext* cx,
 182                                                     Handle<JSScript*> script,
 183                                                     TranscodeBuffer& buffer);
 184
 185 // Check if the compile options and script's flag matches.
 186 //
 187 // JS::DecodeScript* and JS::DecodeOffThreadScript internally check this.
 188 //
 189 // JS::DecodeMultiOffThreadScripts checks some options shared across multiple
 190 // scripts. Caller is responsible for checking each script with this API when
 191 // using the decoded script instead of compiling a new script wiht the given
 192 // options.
 193 extern JS_PUBLIC_API bool CheckCompileOptionsMatch(
 194     const ReadOnlyCompileOptions& options, JSScript* script);
 195
 196 }  // namespace JS
 197
 198 #endif /* js_Transcoding_h */