Extend Builtins with JSFunction and register

Huxpro · facebook-github-bot · commit f25018014729 · 2021-01-25T15:21:44.000-08:00
Summary:
This diff extend the builtins with JSFunction. In summary,

1. `builtins_` in `Runtime` need to be generalized to a vector of
  `Callable *` so it can potentially take a `JSFunction`.

2. Defined JSBuiltin the same way as the other 2.

3. Have a `initJSBuiltins` to register JSFunctions returned from
   internal bytecode. `spawnAsync` is the first of them.

4. Made clear in the `Builtins.def` comments the 3 different types of
   builtins: (Public Native) Builtins, Private (Native) Builtins, and
   the newly added (Private) JS Builtins. Updated some of the
   occurences of such names to reduce confusion.

We'll use the functionality of JSBuiltin in later diffs.

Reviewed By: tmikov

Differential Revision: D23801672

fbshipit-source-id: e0b827c43f3fbacd75f81bf353c949f595e7d548
diff --git a/include/hermes/FrontEndDefs/Builtins.def b/include/hermes/FrontEndDefs/Builtins.def
@@ -7,8 +7,31 @@
 
 ///===----------------------------------------------------------------------===
 /// \file
-/// Define global objects and methods which the compiler can assume have not
-/// been overwritten and can be treated as builtins.
+/// Define Hermes builtin functions.
+///
+/// All builtin functions in Hermes are registered in a vector of `Callable *`
+/// in the runtime with an index as its builtin method id.
+///
+/// There are 3 kinds of builtins in Hermes:
+/// 1. (Public Native) Builtins: those are global objects and methods of JSLib
+///   implemented natively which the compiler can assume have not been
+///   overwritten and can be treated as builtins under the "static builtin"
+///   optimizations (`-fstatic-builtins` flag).
+///
+/// 2. Private (Native) Builtins: those are native functions meant to be only
+///   called internally by the compiler to help with implementing JS features
+///   without introducing extra opcodes. They are notationally written as
+///   `HermesBuiltin_name`.
+///
+/// 3. (Private) JS Builtins: those are JS functions returned from the result of
+///   executing internal bytecode. They are also there to help with implementing
+///   JS features.
+///
+/// At this moment,
+/// Native builtins are invoked via `CallBuiltin` instruction.
+/// JS builtins are invoked via `GetBuiltinClosure` followed by a `Call`.
+///
+/// We might separate them in the future.
 ///
 /// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 /// IMPORTANT: DO NOT FORGET TO INCREASE THE BYTECODE FILE FORMAT VERSION IF
@@ -28,6 +51,12 @@
 #ifndef MARK_FIRST_PRIVATE_BUILTIN
 #define MARK_FIRST_PRIVATE_BUILTIN(name)
 #endif
+#ifndef JS_BUILTIN
+#define JS_BUILTIN(name)
+#endif
+#ifndef MARK_FIRST_JS_BUILTIN
+#define MARK_FIRST_JS_BUILTIN(name)
+#endif
 
 BUILTIN_OBJECT(Array)
 // BUILTIN_METHOD(Array, from)
@@ -109,7 +138,12 @@ PRIVATE_BUILTIN(apply)
 PRIVATE_BUILTIN(exportAll)
 PRIVATE_BUILTIN(exponentiationOperator)
 
+JS_BUILTIN(spawnAsync)
+MARK_FIRST_JS_BUILTIN(spawnAsync)
+
 #undef BUILTIN_OBJECT
 #undef BUILTIN_METHOD
 #undef PRIVATE_BUILTIN
 #undef MARK_FIRST_PRIVATE_BUILTIN
+#undef JS_BUILTIN
+#undef MARK_FIRST_JS_BUILTIN
diff --git a/include/hermes/FrontEndDefs/Builtins.h b/include/hermes/FrontEndDefs/Builtins.h
@@ -8,17 +8,22 @@
 #ifndef HERMES_INST_BUILTINS_H
 #define HERMES_INST_BUILTINS_H
 
+#include <cassert>
+
 namespace hermes {
 
 namespace BuiltinMethod {
 enum Enum : unsigned char {
 #define BUILTIN_METHOD(object, name) object##_##name,
 #define PRIVATE_BUILTIN(name) BUILTIN_METHOD(HermesBuiltin, name)
 #define MARK_FIRST_PRIVATE_BUILTIN(name) _firstPrivate = PRIVATE_BUILTIN(name)
+#define JS_BUILTIN(name) PRIVATE_BUILTIN(name)
+#define MARK_FIRST_JS_BUILTIN(name) _firstJS = JS_BUILTIN(name)
 #include "Builtins.def"
   _count,
   _publicCount = _firstPrivate,
-  _privateCount = _count - _firstPrivate,
+  _privateCount = _firstJS - _firstPrivate,
+  _jsCount = _count - _firstJS,
 };
 
 } // namespace BuiltinMethod
@@ -28,6 +33,15 @@ static_assert(BuiltinMethod::_count <= 256, "More than 256 builtin methods");
 /// Return a string representation of the builtin method name.
 const char *getBuiltinMethodName(int method);
 
+/// Return whether a builtin method is a Native builtin.
+/// Otherwise, it is a JS builtin (as of the only two cases today).
+/// This is more efficient than consulting the GCKind. It only need to perform
+/// a simple comparison between the method index and the JS section offset.
+inline bool isNativeBuiltin(unsigned method) {
+  assert(method < BuiltinMethod::_count && "out of bound BuiltinMethod index");
+  return method < BuiltinMethod::_firstJS;
+};
+
 } // namespace hermes
 
 #endif // HERMES_BCGEN_HBC_BUILTINS_H
diff --git a/include/hermes/VM/Callable.h b/include/hermes/VM/Callable.h
@@ -133,7 +133,7 @@ struct CallableVTable {
 
 /// The abstract base for callable entities, specifically NativeFunction and
 /// Function. It presents the ability to call a function with arguments already
-/// on the stack. Subclasses implement this for native funcitions and
+/// on the stack. Subclasses implement this for native functions and
 /// interpreted functions.
 class Callable : public JSObject {
   using Super = JSObject;
diff --git a/include/hermes/VM/JSLib.h b/include/hermes/VM/JSLib.h
@@ -42,7 +42,7 @@ void initGlobalObject(Runtime *runtime, const JSLibFlags &jsLibFlags);
 /// \c BuiltinMethod::xxx index.
 void createHermesBuiltins(
     Runtime *runtime,
-    llvh::MutableArrayRef<NativeFunction *> builtins);
+    llvh::MutableArrayRef<Callable *> builtins);
 
 std::shared_ptr<RuntimeCommonStorage> createRuntimeCommonStorage(
     bool shouldTrace);
diff --git a/include/hermes/VM/PredefinedStrings.def b/include/hermes/VM/PredefinedStrings.def
@@ -430,6 +430,7 @@ STR(virtualOffset, "virtualOffset")
 STR(fileName, "fileName")
 STR(setPromiseRejectionTrackingHook, "setPromiseRejectionTrackingHook")
 STR(enablePromiseRejectionTracker, "enablePromiseRejectionTracker")
+STR(spawnAsync, "spawnAsync") /* NOLINT */
 
 STR(require, "require")
 STR(requireFast, "requireFast")
diff --git a/include/hermes/VM/Runtime-inline.h b/include/hermes/VM/Runtime-inline.h
@@ -14,9 +14,10 @@
 namespace hermes {
 namespace vm {
 
-inline NativeFunction *Runtime::getBuiltinNativeFunction(
-    unsigned builtinMethodID) {
-  assert(builtinMethodID < BuiltinMethod::_count && "invalid builtinMethodID");
+inline Callable *Runtime::getBuiltinCallable(unsigned builtinMethodID) {
+  assert(
+      builtinMethodID < BuiltinMethod::_count &&
+      "out of bound builtinMethodID");
   return builtins_[builtinMethodID];
 }
 
diff --git a/include/hermes/VM/Runtime.h b/include/hermes/VM/Runtime.h
@@ -314,10 +314,10 @@ class Runtime : public HandleRootOwner,
 
   /// @}
 
-  /// Return a pointer to a builtin native function builtin identified by id.
+  /// Return a pointer to a callable builtin identified by id.
   /// Unfortunately we can't use the enum here, since we don't want to include
   /// the builtins header header.
-  inline NativeFunction *getBuiltinNativeFunction(unsigned builtinMethodID);
+  inline Callable *getBuiltinCallable(unsigned builtinMethodID);
 
   IdentifierTable &getIdentifierTable() {
     return identifierTable_;
@@ -937,19 +937,27 @@ class Runtime : public HandleRootOwner,
   /// \param object is the object where the builtin method is defined as a
   ///   property.
   /// \param methodID is the SymbolID for the name of the method.
-  using ForEachBuiltinCallback = ExecutionStatus(
+  using ForEachPublicNativeBuiltinCallback = ExecutionStatus(
       unsigned methodIndex,
       Predefined::Str objectName,
       Handle<JSObject> &object,
       SymbolID methodID);
 
-  /// Enumerate the builtin methods, and invoke the callback on each method.
-  ExecutionStatus forEachBuiltin(
-      const std::function<ForEachBuiltinCallback> &callback);
+  /// Enumerate all public native builtin methods, and invoke the callback on
+  /// each method.
+  ExecutionStatus forEachPublicNativeBuiltin(
+      const std::function<ForEachPublicNativeBuiltinCallback> &callback);
 
-  /// Populate the builtins table by extracting the values from the global
-  /// object.
-  void initBuiltinTable();
+  /// Populate native builtins into the builtins table.
+  /// Public native builtins are added by extracting the values from the global
+  /// object. Private native builtins are added by \c createHermesBuiltins().
+  void initNativeBuiltins();
+
+  /// Populate JS builtins into the builtins table, after verifying they do
+  /// exist from the result of running internal bytecode.
+  void initJSBuiltins(
+      llvh::MutableArrayRef<Callable *> builtins,
+      Handle<JSObject> jsBuiltins);
 
   /// Walk all the builtin methods, assert that they are not overridden. If they
   /// are, throw an exception. This will be called at most once, before freezing
@@ -1151,8 +1159,8 @@ class Runtime : public HandleRootOwner,
   /// to be scanned as roots in young-gen collections.
   std::vector<PinnedHermesValue> charStrings_{};
 
-  /// Pointers to native implementations of builtins.
-  std::vector<NativeFunction *> builtins_{};
+  /// Pointers to callable implementations of builtins.
+  std::vector<Callable *> builtins_{};
 
   /// True if the builtins are all frozen (non-writable, non-configurable).
   bool builtinsFrozen_{false};
diff --git a/lib/FrontEndDefs/Builtins.cpp b/lib/FrontEndDefs/Builtins.cpp
@@ -14,6 +14,7 @@ namespace hermes {
 static const char *builtinName[] = {
 #define BUILTIN_METHOD(object, name) #object "." #name,
 #define PRIVATE_BUILTIN(name) BUILTIN_METHOD(HermesBuiltin, name)
+#define JS_BUILTIN(name) BUILTIN_METHOD(HermesBuiltin, name)
 #include "hermes/FrontEndDefs/Builtins.def"
 };
 
diff --git a/lib/VM/Interpreter-slowpaths.cpp b/lib/VM/Interpreter-slowpaths.cpp
@@ -304,7 +304,12 @@ ExecutionStatus Interpreter::implCallBuiltin(
     CodeBlock *curCodeBlock,
     uint32_t op3) {
   const Inst *ip = runtime->getCurrentIP();
-  NativeFunction *nf = runtime->getBuiltinNativeFunction(ip->iCallBuiltin.op2);
+  uint8_t methodIndex = ip->iCallBuiltin.op2;
+  Callable *callable = runtime->getBuiltinCallable(methodIndex);
+  assert(
+      isNativeBuiltin(methodIndex) &&
+      "CallBuiltin must take a native builtin.");
+  NativeFunction *nf = vmcast<NativeFunction>(callable);
 
   auto newFrame = StackFramePtr::initFrame(
       runtime->stackPointer_, FRAME, ip, curCodeBlock, op3 - 1, nf, false);
diff --git a/lib/VM/JSLib/HermesBuiltin.cpp b/lib/VM/JSLib/HermesBuiltin.cpp
@@ -762,7 +762,7 @@ hermesBuiltinExportAll(void *, Runtime *runtime, NativeArgs args) {
 
 void createHermesBuiltins(
     Runtime *runtime,
-    llvh::MutableArrayRef<NativeFunction *> builtins) {
+    llvh::MutableArrayRef<Callable *> builtins) {
   auto defineInternMethod = [&](BuiltinMethod::Enum builtinIndex,
                                 Predefined::Str symID,
                                 NativeFunctionPtr func,
diff --git a/lib/VM/Runtime.cpp b/lib/VM/Runtime.cpp
