Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 210 insertions, 0 deletions

diff --git a/js/public/Initialization.h b/js/public/Initialization.h
new file mode 100644
index 0000000000..46715b6c4f
--- /dev/null
+++ b/js/public/Initialization.h
@@ -0,0 +1,210 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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/. */
+
+/* SpiderMonkey initialization and shutdown APIs. */
+
+#ifndef js_Initialization_h
+#define js_Initialization_h
+
+#include "mozilla/Span.h"
+
+#include "jstypes.h"
+
+struct JS_PUBLIC_API JSContext;
+
+namespace JS {
+namespace detail {
+
+enum class InitState { Uninitialized = 0, Initializing, Running, ShutDown };
+
+/**
+ * SpiderMonkey's initialization status is tracked here, and it controls things
+ * that should happen only once across all runtimes.  It's an API requirement
+ * that JS_Init (and JS_ShutDown, if called) be called in a thread-aware
+ * manner, so this (internal -- embedders, don't use!) variable doesn't need to
+ * be atomic.
+ */
+extern JS_PUBLIC_DATA InitState libraryInitState;
+
+enum class FrontendOnly { No, Yes };
+
+extern JS_PUBLIC_API const char* InitWithFailureDiagnostic(
+    bool isDebugBuild, FrontendOnly frontendOnly = FrontendOnly::No);
+
+}  // namespace detail
+}  // namespace JS
+
+// These are equivalent to ICU's |UMemAllocFn|, |UMemReallocFn|, and
+// |UMemFreeFn| types.  The first argument (called |context| in the ICU docs)
+// will always be nullptr and should be ignored.
+typedef void* (*JS_ICUAllocFn)(const void*, size_t size);
+typedef void* (*JS_ICUReallocFn)(const void*, void* p, size_t size);
+typedef void (*JS_ICUFreeFn)(const void*, void* p);
+
+/**
+ * This function can be used to track memory used by ICU.  If it is called, it
+ * *must* be called before JS_Init.  Don't use it unless you know what you're
+ * doing!
+ */
+extern JS_PUBLIC_API bool JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn,
+                                                   JS_ICUReallocFn reallocFn,
+                                                   JS_ICUFreeFn freeFn);
+
+/**
+ * Initialize SpiderMonkey, returning true only if initialization succeeded.
+ * Once this method has succeeded, it is safe to call JS_NewContext and other
+ * JSAPI methods.
+ *
+ * This method must be called before any other JSAPI method is used on any
+ * thread.  Once it has been used, it is safe to call any JSAPI method, and it
+ * remains safe to do so until JS_ShutDown is correctly called.
+ *
+ * It is currently not possible to initialize SpiderMonkey multiple times (that
+ * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
+ * again).  This restriction may eventually be lifted.
+ */
+inline bool JS_Init(void) {
+#ifdef DEBUG
+  return !JS::detail::InitWithFailureDiagnostic(true);
+#else
+  return !JS::detail::InitWithFailureDiagnostic(false);
+#endif
+}
+
+/**
+ * A variant of JS_Init. On success it returns nullptr. On failure it returns a
+ * pointer to a string literal that describes how initialization failed, which
+ * can be useful for debugging purposes.
+ */
+inline const char* JS_InitWithFailureDiagnostic(void) {
+#ifdef DEBUG
+  return JS::detail::InitWithFailureDiagnostic(true);
+#else
+  return JS::detail::InitWithFailureDiagnostic(false);
+#endif
+}
+
+/**
+ * A lightweight variant of JS_Init, which skips initializing runtime-specific
+ * part.
+ * Suitable for processes where only JSContext-free stencil-APIs are used.
+ */
+inline bool JS_FrontendOnlyInit(void) {
+#ifdef DEBUG
+  return !JS::detail::InitWithFailureDiagnostic(true,
+                                                JS::detail::FrontendOnly::Yes);
+#else
+  return !JS::detail::InitWithFailureDiagnostic(false,
+                                                JS::detail::FrontendOnly::Yes);
+#endif
+}
+
+/*
+ * Returns true if SpiderMonkey has been initialized successfully, even if it
+ * has possibly been shut down.
+ *
+ * Note that it is the responsibility of the embedder to call JS_Init() and
+ * JS_ShutDown() at the correct times, and therefore this API should ideally not
+ * be necessary to use.  This is only intended to be used in cases where the
+ * embedder isn't in full control of deciding whether to initialize SpiderMonkey
+ * or hand off the task to another consumer.
+ */
+inline bool JS_IsInitialized(void) {
+  return JS::detail::libraryInitState >= JS::detail::InitState::Running;
+}
+
+namespace JS {
+
+// Reference to a sequence of bytes.
+// TODO: This type should be Span<cont uint8_t> (Bug 1709135)
+using SelfHostedCache = mozilla::Span<const uint8_t>;
+
+// Callback function used to copy the SelfHosted content to memory or to disk.
+using SelfHostedWriter = bool (*)(JSContext*, SelfHostedCache);
+
+/*
+ * Initialize the runtime's self-hosted code. Embeddings should call this
+ * exactly once per runtime/context, before the first JS_NewGlobalObject
+ * call.
+ *
+ * This function parses the self-hosted code, except if the provided cache span
+ * is not empty, in which case the self-hosted content is decoded from the span.
+ *
+ * The cached content provided as argument, when non-empty, should come from the
+ * a previous execution of JS::InitSelfHostedCode where a writer was registered.
+ * The content should come from the same version of the binary, otherwise this
+ * would cause an error.
+ *
+ * The cached content provided with the Span should remain alive until
+ * JS_Shutdown is called.
+ *
+ * The writer callback given as argument would be called by when the result of
+ * the parser is ready to be cached. The writer is in charge of saving the
+ * content in memory or on disk. The span given as argument of the writer only
+ * last for the time of the call, and contains the content to be saved.
+ *
+ * The writer is not called if the cached content given as argument of
+ * InitSelfHostedCode is non-empty.
+ *
+ * Errors returned by the writer callback would bubble up through
+ * JS::InitSelfHostedCode.
+ *
+ * The cached content provided by the writer callback is safe to reuse across
+ * threads, and even across multiple executions as long as the executable is
+ * identical.
+ *
+ * NOTE: This may not set a pending exception in the case of OOM since this
+ *       runs very early in startup.
+ */
+JS_PUBLIC_API bool InitSelfHostedCode(JSContext* cx,
+                                      SelfHostedCache cache = nullptr,
+                                      SelfHostedWriter writer = nullptr);
+
+/*
+ * Permanently disable the JIT backend for this process. This disables the JS
+ * Baseline Interpreter, JIT compilers, regular expression JIT and support for
+ * WebAssembly.
+ *
+ * If called, this *must* be called before JS_Init.
+ */
+JS_PUBLIC_API void DisableJitBackend();
+
+}  // namespace JS
+
+/**
+ * Destroy free-standing resources allocated by SpiderMonkey, not associated
+ * with any runtime, context, or other structure.
+ *
+ * This method should be called after all other JSAPI data has been properly
+ * cleaned up: every new runtime must have been destroyed, every new context
+ * must have been destroyed, and so on.  Calling this method before all other
+ * resources have been destroyed has undefined behavior.
+ *
+ * Failure to call this method, at present, has no adverse effects other than
+ * leaking memory.  This may not always be the case; it's recommended that all
+ * embedders call this method when all other JSAPI operations have completed.
+ *
+ * It is currently not possible to initialize SpiderMonkey multiple times (that
+ * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
+ * again).  This restriction may eventually be lifted.
+ */
+extern JS_PUBLIC_API void JS_ShutDown(void);
+
+/**
+ * A variant of JS_ShutDown for process which used JS_FrontendOnlyInit instead
+ * of JS_Init.
+ */
+extern JS_PUBLIC_API void JS_FrontendOnlyShutDown(void);
+
+#if defined(ENABLE_WASM_SIMD) && \
+    (defined(JS_CODEGEN_X64) || defined(JS_CODEGEN_X86))
+namespace JS {
+// Enable support for AVX instructions in the JIT/Wasm backend on x86/x64
+// platforms. Must be called before JS_Init*.
+void SetAVXEnabled(bool enabled);
+}  // namespace JS
+#endif
+
+#endif /* js_Initialization_h */