js/public/OffThreadScriptCompilation.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  * Types and functions related to the compilation of JavaScript off the
   8  * direct JSAPI-using thread.
   9  */
  10
  11 #ifndef js_OffThreadScriptCompilation_h
  12 #define js_OffThreadScriptCompilation_h
  13
  14 #include "mozilla/Range.h"   // mozilla::Range
  15 #include "mozilla/Utf8.h"    // mozilla::Utf8Unit
  16 #include "mozilla/Vector.h"  // mozilla::Vector
  17
  18 #include <stddef.h>  // size_t
  19
  20 #include "jstypes.h"  // JS_PUBLIC_API
  21
  22 #include "js/CompileOptions.h"  // JS::ReadOnlyCompileOptions
  23 #include "js/GCVector.h"        // JS::GCVector
  24 #include "js/Transcoding.h"     // JS::TranscodeSource
  25
  26 struct JSContext;
  27 class JSScript;
  28
  29 namespace JS {
  30
  31 template <typename UnitT>
  32 class SourceText;
  33
  34 }  // namespace JS
  35
  36 namespace JS {
  37
  38 class OffThreadToken;
  39
  40 using OffThreadCompileCallback = void (*)(OffThreadToken* token,
  41                                           void* callbackData);
  42
  43 /*
  44  * Off thread compilation control flow.
  45  *
  46  * After successfully triggering an off thread compile of a script, the
  47  * callback will eventually be invoked with the specified data and a token
  48  * for the compilation. The callback will be invoked while off thread,
  49  * so must ensure that its operations are thread safe. Afterwards, one of the
  50  * following functions must be invoked on the runtime's main thread:
  51  *
  52  * - FinishOffThreadScript, to get the result script (or nullptr on failure).
  53  * - CancelOffThreadScript, to free the resources without creating a script.
  54  *
  55  * The characters passed in to CompileOffThread must remain live until the
  56  * callback is invoked, and the resulting script will be rooted until the call
  57  * to FinishOffThreadScript.
  58  */
  59
  60 extern JS_PUBLIC_API bool CanCompileOffThread(
  61     JSContext* cx, const ReadOnlyCompileOptions& options, size_t length);
  62
  63 extern JS_PUBLIC_API bool CompileOffThread(
  64     JSContext* cx, const ReadOnlyCompileOptions& options,
  65     SourceText<char16_t>& srcBuf, OffThreadCompileCallback callback,
  66     void* callbackData);
  67
  68 // NOTE: Unlike for the normal sync compilation functions, this function NEVER
  69 //       INFLATES TO UTF-16.  Therefore, it is ALWAYS invoking experimental
  70 //       UTF-8 support.  Inflate to UTF-16 yourself and use the other overload
  71 //       if you're unable to take a risk using unstable functionality.
  72 extern JS_PUBLIC_API bool CompileOffThread(
  73     JSContext* cx, const ReadOnlyCompileOptions& options,
  74     SourceText<mozilla::Utf8Unit>& srcBuf, OffThreadCompileCallback callback,
  75     void* callbackData);
  76
  77 extern JS_PUBLIC_API JSScript* FinishOffThreadScript(JSContext* cx,
  78                                                      OffThreadToken* token);
  79
  80 extern JS_PUBLIC_API void CancelOffThreadScript(JSContext* cx,
  81                                                 OffThreadToken* token);
  82
  83 extern JS_PUBLIC_API bool CompileOffThreadModule(
  84     JSContext* cx, const ReadOnlyCompileOptions& options,
  85     SourceText<char16_t>& srcBuf, OffThreadCompileCallback callback,
  86     void* callbackData);
  87
  88 // NOTE: Unlike for the normal sync compilation functions, this function NEVER
  89 //       INFLATES TO UTF-16.  Therefore, it is ALWAYS invoking experimental
  90 //       UTF-8 support.  Inflate to UTF-16 yourself and use the other overload
  91 //       if you're unable to take a risk using unstable functionality.
  92 extern JS_PUBLIC_API bool CompileOffThreadModule(
  93     JSContext* cx, const ReadOnlyCompileOptions& options,
  94     SourceText<mozilla::Utf8Unit>& srcBuf, OffThreadCompileCallback callback,
  95     void* callbackData);
  96
  97 extern JS_PUBLIC_API JSObject* FinishOffThreadModule(JSContext* cx,
  98                                                      OffThreadToken* token);
  99
 100 extern JS_PUBLIC_API void CancelOffThreadModule(JSContext* cx,
 101                                                 OffThreadToken* token);
 102
 103 extern JS_PUBLIC_API bool CanDecodeOffThread(
 104     JSContext* cx, const ReadOnlyCompileOptions& options, size_t length);
 105
 106 extern JS_PUBLIC_API bool DecodeOffThreadScript(
 107     JSContext* cx, const ReadOnlyCompileOptions& options,
 108     mozilla::Vector<uint8_t>& buffer /* TranscodeBuffer& */, size_t cursor,
 109     OffThreadCompileCallback callback, void* callbackData);
 110
 111 extern JS_PUBLIC_API bool DecodeOffThreadScript(
 112     JSContext* cx, const ReadOnlyCompileOptions& options,
 113     const mozilla::Range<uint8_t>& range /* TranscodeRange& */,
 114     OffThreadCompileCallback callback, void* callbackData);
 115
 116 extern JS_PUBLIC_API JSScript* FinishOffThreadScriptDecoder(
 117     JSContext* cx, OffThreadToken* token);
 118
 119 extern JS_PUBLIC_API void CancelOffThreadScriptDecoder(JSContext* cx,
 120                                                        OffThreadToken* token);
 121
 122 extern JS_PUBLIC_API bool DecodeMultiOffThreadScripts(
 123     JSContext* cx, const ReadOnlyCompileOptions& options,
 124     mozilla::Vector<TranscodeSource>& sources,
 125     OffThreadCompileCallback callback, void* callbackData);
 126
 127 extern JS_PUBLIC_API bool FinishMultiOffThreadScriptsDecoder(
 128     JSContext* cx, OffThreadToken* token,
 129     MutableHandle<GCVector<JSScript*>> scripts);
 130
 131 extern JS_PUBLIC_API void CancelMultiOffThreadScriptsDecoder(
 132     JSContext* cx, OffThreadToken* token);
 133
 134 #if defined(JS_BUILD_BINAST)
 135
 136 extern JS_PUBLIC_API bool CanDecodeBinASTOffThread(
 137     JSContext* cx, const ReadOnlyCompileOptions& options, size_t length);
 138
 139 extern JS_PUBLIC_API bool DecodeBinASTOffThread(
 140     JSContext* cx, const ReadOnlyCompileOptions& options, const uint8_t* buf,
 141     size_t length, OffThreadCompileCallback callback, void* callbackData);
 142
 143 extern JS_PUBLIC_API JSScript* FinishOffThreadBinASTDecode(
 144     JSContext* cx, OffThreadToken* token);
 145
 146 #endif  // defined(JS_BUILD_BINAST)
 147
 148 }  // namespace JS
 149
 150 #endif /* js_OffThreadScriptCompilation_h */