Move IHermes to jsi/hermes.h (#53418)

Summary:
Pull Request resolved: #53418

Expose these methods so that we can access from RN code. To minimize
the change, a few methods that depend on other headers or preprocessor
flags are wrapped into IHermesExtra in hermes/API/hermes.h.

Changelog: [Internal]

Reviewed By: tsaichien

Differential Revision: D80740969

fbshipit-source-id: 79565d851bc1b0833931f4fe7fb62d89d3d669ef

Author: lavenzg

packages/react-native/ReactCommon/jsi/jsi/hermes.h

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+struct SHUnit;
+struct SHRuntime;
+namespace hermes::vm {
+class GCExecTrace;
+}
+
+namespace facebook::hermes {
+
+namespace debugger {
+class Debugger;
+}
+
+/// Interface for Hermes-specific runtime methods.The actual implementations of
+/// the pure virtual methods are provided by Hermes API.
+class JSI_EXPORT IHermes : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0xe85cfa22,
+      0xdfae,
+      0x11ef,
+      0xa6f7,
+      0x325096b39f47};
+
+  /// Return a ICast pointer to an object that be cast into the interface
+  /// IHermesRootAPI. This root API object has static lifetime.
+  virtual ICast* getHermesRootAPI() = 0;
+
+  /// Serialize the sampled stack to the format expected by DevTools'
+  /// Profiler.stop return type.
+  virtual void sampledTraceToStreamInDevToolsFormat(std::ostream& stream) = 0;
+
+  /// Resets the timezone offset cache used by Hermes for performance
+  /// optimization. Hermes maintains a cached timezone offset to accelerate date
+  /// and time calculations. However, this cache does not automatically detect
+  /// changes to the system timezone. When the system timezone changes, the
+  /// integration layer (e.g., React Native) must call this method to invalidate
+  /// the cache and ensure correct time calculations.
+  ///
+  /// \note Call this method immediately after detecting any timezone change in
+  /// the integrator.
+  virtual void resetTimezoneCache() = 0;
+
+  /// Load a new segment into the Runtime.
+  /// The \param context must be a valid RequireContext retrieved from JS
+  /// using `require.context`.
+  virtual void loadSegment(
+      std::unique_ptr<const jsi::Buffer> buffer,
+      const jsi::Value& context) = 0;
+
+  /// Gets a guaranteed unique id for an Object (or, respectively, String
+  /// or PropNameId), which is assigned at allocation time and is
+  /// static throughout that object's (or string's, or PropNameID's)
+  /// lifetime.
+  virtual uint64_t getUniqueID(const jsi::Object& o) const = 0;
+  virtual uint64_t getUniqueID(const jsi::BigInt& s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::String& s) const = 0;
+  virtual uint64_t getUniqueID(const jsi::PropNameID& pni) const = 0;
+  virtual uint64_t getUniqueID(const jsi::Symbol& sym) const = 0;
+
+  /// Same as the other \c getUniqueID, except it can return 0 for some values.
+  /// 0 means there is no ID associated with the value.
+  virtual uint64_t getUniqueID(const jsi::Value& val) const = 0;
+
+  /// From an ID retrieved from \p getUniqueID, go back to the object.
+  /// NOTE: This is much slower in general than the reverse operation, and takes
+  /// up more memory. Don't use this unless it's absolutely necessary.
+  /// \return a jsi::Object if a matching object is found, else returns null.
+  virtual jsi::Value getObjectForID(uint64_t id) = 0;
+
+  /// Get a structure representing the execution history (currently just of
+  /// GC, but will be generalized as necessary), to aid in debugging
+  /// non-deterministic execution.
+  virtual const ::hermes::vm::GCExecTrace& getGCExecTrace() const = 0;
+
+  /// Get IO tracking (aka HBC page access) info as a JSON string.
+  /// See hermes::vm::Runtime::getIOTrackingInfoJSON() for conditions
+  /// needed for there to be useful output.
+  virtual std::string getIOTrackingInfoJSON() = 0;
+
+  /// \return a reference to the Debugger for this Runtime.
+  virtual debugger::Debugger& getDebugger() = 0;
+
+  /// Register this runtime and thread for sampling profiler. Before using the
+  /// runtime on another thread, invoke this function again from the new thread
+  /// to make the sampling profiler target the new thread (and forget the old
+  /// thread).
+  virtual void registerForProfiling() = 0;
+  /// Unregister this runtime for sampling profiler.
+  virtual void unregisterForProfiling() = 0;
+
+  /// Define methods to interrupt JS execution and set time limits.
+  /// All JS compiled to bytecode via prepareJS, or evaluateJS, will support
+  /// interruption and time limit monitoring if the runtime is configured with
+  /// AsyncBreakCheckInEval. If JS prepared in other ways is executed, care must
+  /// be taken to ensure that it is compiled in a mode that supports it (i.e.,
+  /// the emitted code contains async break checks).
+
+  /// Asynchronously terminates the current execution. This can be called on
+  /// any thread.
+  virtual void asyncTriggerTimeout() = 0;
+
+  /// Register this runtime for execution time limit monitoring, with a time
+  /// limit of \p timeoutInMs milliseconds.
+  /// See compilation notes above.
+  virtual void watchTimeLimit(uint32_t timeoutInMs) = 0;
+  /// Unregister this runtime for execution time limit monitoring.
+  virtual void unwatchTimeLimit() = 0;
+
+  /// Same as \c evaluate JavaScript but with a source map, which will be
+  /// applied to exception traces and debug information.
+  ///
+  /// This is an experimental Hermes-specific API. In the future it may be
+  /// renamed, moved or combined with another API, but the provided
+  /// functionality will continue to be available in some form.
+  virtual jsi::Value evaluateJavaScriptWithSourceMap(
+      const std::shared_ptr<const jsi::Buffer>& buffer,
+      const std::shared_ptr<const jsi::Buffer>& sourceMapBuf,
+      const std::string& sourceURL) = 0;
+
+  /// Associate the SHUnit returned by \p shUnitCreator with this runtime and
+  /// run its initialization code. The unit will be freed when the runtime is
+  /// destroyed.
+  virtual jsi::Value evaluateSHUnit(SHUnit* (*shUnitCreator)()) = 0;
+
+  /// Retrieve the underlying SHRuntime.
+  virtual SHRuntime* getSHRuntime() noexcept = 0;
+
+  /// Returns the underlying low level Hermes VM runtime instance.
+  /// This function is considered unsafe and unstable.
+  /// Direct use of a vm::Runtime should be avoided as the lower level APIs are
+  /// unsafe and they can change without notice.
+  virtual void* getVMRuntimeUnsafe() const = 0;
+
+ protected:
+  ~IHermes() = default;
+};
+} // namespace facebook::hermes