Add for await of (#1559)

Summary:
This PR introduces support for the `for await of` syntax through IR. In detail:

- The helper function `_makeAsyncIterator` is used to create an async iterator for a given iterable. It checks if an async iterator method is available; if not, it creates an async iterator from a synchronous iterator by wrapping its results in promises.
- Added a `genAsyncForOfStatement` which handles the for await of loop by iterating over the async iterator object. It follows the same rules described [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)

Pull Request resolved: #1559

Test Plan: - Added 3 unit tests to cover the main behavior of `for await of` loop

Reviewed By: tmikov

Differential Revision: D72175189

Pulled By: avp

fbshipit-source-id: 20933dbd7f19fab48550b64db5255ecaf0612b8e

Author: trossimel-sc

include/hermes/FrontEndDefs/Builtins.def

@@ -156,6 +156,7 @@ PRIVATE_BUILTIN(functionPrototypeCall)
 
 JS_BUILTIN(spawnAsync)
 MARK_FIRST_JS_BUILTIN(spawnAsync)
+JS_BUILTIN(makeAsyncIterator)
 
 #undef NORMAL_OBJECT
 #undef NORMAL_METHOD

include/hermes/VM/PredefinedStrings.def

@@ -417,6 +417,7 @@ STR(keyFor, "keyFor")
 STR(hasInstance, "hasInstance")
 STR(isConcatSpreadable, "isConcatSpreadable")
 STR(iterator, "iterator")
+STR(asyncIterator, "asyncIterator")
 STR(toPrimitive, "toPrimitive")
 STR(toStringTag, "toStringTag")
 
@@ -473,6 +474,7 @@ STR(fileName, "fileName")
 STR(setPromiseRejectionTrackingHook, "setPromiseRejectionTrackingHook")
 STR(enablePromiseRejectionTracker, "enablePromiseRejectionTracker")
 STR(spawnAsync, "spawnAsync") /* NOLINT */
+STR(makeAsyncIterator, "makeAsyncIterator") /* NOLINT */
 
 STR(SHBuiltin, "$SHBuiltin")
 
@@ -488,6 +490,7 @@ STR(squareObjectNull, "[object Null]")
 STR(squareObjectGlobal, "[object global]")
 STR(squareSymbolHasInstance, "[Symbol.hasInstance]")
 STR(squareSymbolIterator, "[Symbol.iterator]")
+STR(squareSymbolAsyncIterator, "[Symbol.asyncIterator]")
 STR(squareSymbolToPrimitive, "[Symbol.toPrimitive]")
 STR(squareSymbolToStringTag, "[Symbol.toStringTag]")
 STR(squareSymbolMatch, "[Symbol.match]")

include/hermes/VM/PredefinedSymbols.def

@@ -15,6 +15,7 @@
 
 SYM(SymbolHasInstance, "Symbol.hasInstance")
 SYM(SymbolIterator, "Symbol.iterator")
+SYM(SymbolAsyncIterator, "Symbol.asyncIterator")
 SYM(SymbolIsConcatSpreadable, "Symbol.isConcatSpreadable")
 SYM(SymbolToPrimitive, "Symbol.toPrimitive")
 SYM(SymbolToStringTag, "Symbol.toStringTag")

lib/IRGen/ESTreeIRGen-expr.cpp

@@ -1997,7 +1997,7 @@ Value *ESTreeIRGen::genYieldStarExpr(ESTree::YieldExpressionNode *Y) {
       // emitNormalCleanup.
       []() {},
       // emitHandler.
-      [this, exitBlock, result, &iteratorRecord, &resumeGenTryStartBB](
+      [this, exitBlock, result, &iteratorRecord, &resumeGenTryStartBB, Y](
           BasicBlock *getNextBlock) {
         auto *catchReg = Builder.createCatchInst();
 
@@ -2052,7 +2052,7 @@ Value *ESTreeIRGen::genYieldStarExpr(ESTree::YieldExpressionNode *Y) {
         // going to terminate the yield* loop. But first we need to give
         // iterator a chance to clean up.
         Builder.setInsertionBlock(noThrowMethodBB);
-        emitIteratorCloseSlow(iteratorRecord, false);
+        emitIteratorCloseSlow(Y, iteratorRecord, false);
         Builder.createThrowTypeErrorInst(Builder.getLiteralString(
             "yield* delegate must have a .throw() method"));
       });

lib/IRGen/ESTreeIRGen-stmt.cpp

@@ -54,7 +54,7 @@ void ESTreeIRGen::genStatement(ESTree::Node *stmt) {
   }
 
   if (auto *FOS = llvh::dyn_cast<ESTree::ForOfStatementNode>(stmt)) {
-    return genForOfStatement(FOS);
+    return FOS->_await ? genAsyncForOfStatement(FOS) : genForOfStatement(FOS);
   }
 
   if (auto *Ret = llvh::dyn_cast<ESTree::ReturnStatementNode>(stmt)) {
@@ -974,6 +974,104 @@ void ESTreeIRGen::genForOfStatement(ESTree::ForOfStatementNode *forOfStmt) {
   Builder.setInsertionBlock(exitBlock);
 }
 
+void ESTreeIRGen::genAsyncForOfStatement(
+    ESTree::ForOfStatementNode *forOfStmt) {
+  auto *outerScope = curFunction()->curScope();
+
+  // If block scoping is enabled, check if anything in the loop might capture,
+  // so we know whether to create inner scopes for the loop.
+  bool createInnerScopes = Mod->getContext().getEnableES6BlockScoping() &&
+      !treeDoesNotCapture(forOfStmt);
+
+  // Create an inner scope for the loop init if needed and set it as the top
+  // scope. All loop variables will be declared in this scope.
+  if (createInnerScopes) {
+    auto *initScope = Builder.createCreateScopeInst(
+        curFunction()->getOrCreateInnerVariableScope(forOfStmt), outerScope);
+    curFunction()->setCurScope(initScope);
+  }
+
+  emitScopeDeclarations(forOfStmt->getScope());
+
+  auto *function = Builder.getInsertionBlock()->getParent();
+  auto *getNextBlock = Builder.createBasicBlock(function);
+  auto *bodyBlock = Builder.createBasicBlock(function);
+  auto *exitBlock = Builder.createBasicBlock(function);
+
+  // Initialize the goto labels.
+  curFunction()->initLabel(forOfStmt, exitBlock, getNextBlock);
+
+  auto *exprValue = genExpression(forOfStmt->_right);
+  const IteratorRecordSlow iteratorRecord = emitGetAsyncIteratorSlow(exprValue);
+
+  Builder.createBranchInst(getNextBlock);
+
+  // Attempt to retrieve the next value. If iteration is complete, finish the
+  // loop. This stays outside the SurroundingTry below because exceptions in
+  // `.next()` should not call `.return()` on the iterator.
+  Builder.setInsertionBlock(getNextBlock);
+  auto *nextResult = genYieldOrAwaitExpr(emitIteratorNextSlow(iteratorRecord));
+  auto *done = emitIteratorCompleteSlow(nextResult);
+  Builder.createCondBranchInst(done, exitBlock, bodyBlock);
+
+  Builder.setInsertionBlock(bodyBlock);
+
+  // Create a scope for the body if needed.
+  if (createInnerScopes) {
+    auto *innerScope = Builder.createCreateScopeInst(
+        curFunction()->curScope()->getVariableScope(), outerScope);
+    curFunction()->setCurScope(innerScope);
+  }
+
+  auto *nextValue = emitIteratorValueSlow(nextResult);
+
+  emitTryCatchScaffolding(
+      getNextBlock,
+      // emitBody.
+      [this, forOfStmt, nextValue, &iteratorRecord, getNextBlock](
+          BasicBlock *catchBlock) {
+        // Generate IR for the body of Try
+        SurroundingTry thisTry{
+            curFunction(),
+            forOfStmt,
+            catchBlock,
+            {},
+            [this, &iteratorRecord, getNextBlock, forOfStmt](
+                ESTree::Node *,
+                ControlFlowChange cfc,
+                BasicBlock *continueTarget) {
+              // Only emit the iteratorClose if this is a
+              // 'break' or if the target of the control flow
+              // change is outside the current loop. If
+              // continuing the existing loop, do not close
+              // the iterator.
+              if (cfc == ControlFlowChange::Break ||
+                  continueTarget != getNextBlock)
+                emitAsyncIteratorCloseSlow(forOfStmt, iteratorRecord, false);
+            }};
+
+        // Note: obtaining the value is not protected, but storing it is.
+        createLRef(forOfStmt->_left, false).emitStore(nextValue);
+
+        genStatement(forOfStmt->_body);
+        Builder.setLocation(SourceErrorManager::convertEndToLocation(
+            forOfStmt->_body->getSourceRange()));
+      },
+      // emitNormalCleanup.
+      []() {},
+      // emitHandler.
+      [this, &iteratorRecord, forOfStmt](BasicBlock *) {
+        auto *catchReg = Builder.createCatchInst();
+        emitAsyncIteratorCloseSlow(forOfStmt, iteratorRecord, true);
+        Builder.createThrowInst(catchReg);
+      });
+
+  // Restore the outer scope for subsequent code.
+  curFunction()->setCurScope(outerScope);
+
+  Builder.setInsertionBlock(exitBlock);
+}
+
 void ESTreeIRGen::genForOfFastArrayStatement(
     ESTree::ForOfStatementNode *forOfStmt,
     flow::ArrayType *type) {

lib/IRGen/ESTreeIRGen.cpp

@@ -583,6 +583,12 @@ Value *ESTreeIRGen::emitIteratorSymbol() {
       "iterator");
 }
 
+Value *ESTreeIRGen::emitAsyncIteratorSymbol() {
+  return Builder.createLoadPropertyInst(
+      Builder.createGetBuiltinClosureInst(BuiltinMethod::globalThis_Symbol),
+      "asyncIterator");
+}
+
 ESTreeIRGen::IteratorRecordSlow ESTreeIRGen::emitGetIteratorSlow(Value *obj) {
   auto *method = Builder.createLoadPropertyInst(obj, emitIteratorSymbol());
   auto *iterator = Builder.createCallInst(
@@ -594,6 +600,21 @@ ESTreeIRGen::IteratorRecordSlow ESTreeIRGen::emitGetIteratorSlow(Value *obj) {
   return {iterator, nextMethod};
 }
 
+ESTreeIRGen::IteratorRecordSlow ESTreeIRGen::emitGetAsyncIteratorSlow(
+    Value *obj) {
+  auto *makeAsyncIterator = Builder.createGetBuiltinClosureInst(
+      BuiltinMethod::HermesBuiltin_makeAsyncIterator);
+
+  auto *iterator = Builder.createCallInst(
+      makeAsyncIterator,
+      Builder.getLiteralUndefined(),
+      Builder.getLiteralUndefined(),
+      {obj});
+  auto *nextMethod = Builder.createLoadPropertyInst(iterator, "next");
+
+  return {iterator, nextMethod};
+}
+
 Value *ESTreeIRGen::emitIteratorNextSlow(IteratorRecordSlow iteratorRecord) {
   auto *nextResult = Builder.createCallInst(
       iteratorRecord.nextMethod,
@@ -612,9 +633,11 @@ Value *ESTreeIRGen::emitIteratorValueSlow(Value *iterResult) {
   return Builder.createLoadPropertyInst(iterResult, "value");
 }
 
-void ESTreeIRGen::emitIteratorCloseSlow(
+void ESTreeIRGen::_emitIteratorCloseImpl(
+    ESTree::Node *astNode,
     hermes::irgen::ESTreeIRGen::IteratorRecordSlow iteratorRecord,
-    bool ignoreInnerException) {
+    bool ignoreInnerException,
+    bool isAsyncIterator) {
   auto *haveReturn = Builder.createBasicBlock(Builder.getFunction());
   auto *noReturn = Builder.createBasicBlock(Builder.getFunction());
 
@@ -632,12 +655,24 @@ void ESTreeIRGen::emitIteratorCloseSlow(
     emitTryCatchScaffolding(
         noReturn,
         // emitBody.
-        [this, returnMethod, &iteratorRecord](BasicBlock * /*catchBlock*/) {
-          Builder.createCallInst(
+        [this, returnMethod, &iteratorRecord, isAsyncIterator, astNode](
+            BasicBlock *catchBlock) {
+          SurroundingTry thisTry{
+              curFunction(),
+              astNode,
+              catchBlock,
+              {},
+              [](ESTree::Node *,
+                 ControlFlowChange cfc,
+                 BasicBlock *continueTarget) {}};
+
+          auto *callResult = Builder.createCallInst(
               returnMethod,
               /* newTarget */ Builder.getLiteralUndefined(),
               iteratorRecord.iterator,
               {});
+          if (isAsyncIterator)
+            genYieldOrAwaitExpr(callResult);
         },
         // emitNormalCleanup.
         []() {},
@@ -648,18 +683,34 @@ void ESTreeIRGen::emitIteratorCloseSlow(
           Builder.createBranchInst(nextBlock);
         });
   } else {
-    auto *innerResult = Builder.createCallInst(
+    auto *callResult = Builder.createCallInst(
         returnMethod,
         /* newTarget */ Builder.getLiteralUndefined(),
         iteratorRecord.iterator,
         {});
-    emitEnsureObject(innerResult, "iterator.return() did not return an object");
+    emitEnsureObject(
+        isAsyncIterator ? genYieldOrAwaitExpr(callResult) : callResult,
+        "iterator.return() did not return an object");
     Builder.createBranchInst(noReturn);
   }
 
   Builder.setInsertionBlock(noReturn);
 }
 
+void ESTreeIRGen::emitIteratorCloseSlow(
+    ESTree::Node *astNode,
+    hermes::irgen::ESTreeIRGen::IteratorRecordSlow iteratorRecord,
+    bool ignoreInnerException) {
+  _emitIteratorCloseImpl(astNode, iteratorRecord, ignoreInnerException, false);
+}
+
+void ESTreeIRGen::emitAsyncIteratorCloseSlow(
+    ESTree::Node *astNode,
+    hermes::irgen::ESTreeIRGen::IteratorRecordSlow iteratorRecord,
+    bool ignoreInnerException) {
+  _emitIteratorCloseImpl(astNode, iteratorRecord, ignoreInnerException, true);
+}
+
 ESTreeIRGen::IteratorRecord ESTreeIRGen::emitGetIterator(Value *obj) {
   // Each of these will be modified by "next", so we use a stack storage.
   auto *iterStorage = Builder.createAllocStackInst(

lib/IRGen/ESTreeIRGen.h

@@ -704,6 +704,7 @@ class ESTreeIRGen {
   void genForOfFastArrayStatement(
       ESTree::ForOfStatementNode *forOfStmt,
       flow::ArrayType *type);
+  void genAsyncForOfStatement(ESTree::ForOfStatementNode *forOfStmt);
   void genWhileLoop(ESTree::WhileStatementNode *loop);
   void genDoWhileLoop(ESTree::DoWhileStatementNode *loop);
 
@@ -1460,6 +1461,9 @@ class ESTreeIRGen {
   /// \return the internal value @@iterator
   Value *emitIteratorSymbol();
 
+  /// \return the internal value @@asyncIterator
+  Value *emitAsyncIteratorSymbol();
+
   /// IteratorRecord as defined in ES2018 7.4.1 GetIterator
   struct IteratorRecordSlow {
     Value *iterator;
@@ -1478,6 +1482,15 @@ class ESTreeIRGen {
   /// \return (iterator, nextMethod)
   IteratorRecordSlow emitGetIteratorSlow(Value *obj);
 
+  /// Call obj[@@asyncIterator], which should return an async iterator,
+  /// and return the iterator itself and its \c next() method.
+  ///
+  /// NOTE: This API is slow and should only be used if it is necessary to
+  /// provide a value to the `next()` method on the iterator.
+  ///
+  /// \return (iterator, nextMethod)
+  IteratorRecordSlow emitGetAsyncIteratorSlow(Value *obj);
+
   /// ES2018 7.4.2 IteratorNext
   /// https://www.ecma-international.org/ecma-262/9.0/index.html#sec-iteratornext
   ///
@@ -1499,13 +1512,35 @@ class ESTreeIRGen {
   /// \return \c iterResult.value
   Value *emitIteratorValueSlow(Value *iterResult);
 
+  /// A helper called only from \c emitIteratorCloseSlow or
+  /// emitAsyncIteratorCloseSlow. It performs the actual work.
+  void _emitIteratorCloseImpl(
+      ESTree::Node *astNode,
+      IteratorRecordSlow iteratorRecord,
+      bool ignoreInnerException,
+      bool isAsyncIterator);
+
   /// ES2018 7.4.6 IteratorClose
   /// https://www.ecma-international.org/ecma-262/9.0/index.html#sec-iteratorclose
   ///
+  /// \param astNode the caller AST node
   /// \param ignoreInnerException if set, exceptions thrown by the \c
   ///     iterator.return() method will be ignored and its result will not be
   ///     checked whether it is an object.
   void emitIteratorCloseSlow(
+      ESTree::Node *astNode,
+      IteratorRecordSlow iteratorRecord,
+      bool ignoreInnerException);
+
+  /// ES2018 7.4.7 AsyncIteratorClose
+  /// https://www.ecma-international.org/ecma-262/9.0/index.html#sec-asynciteratorclose
+  ///
+  /// \param astNode the caller AST node
+  /// \param ignoreInnerException if set, exceptions thrown by the \c
+  ///     async iterator.return() method will be ignored and its result will not
+  ///     be checked whether it is an object.
+  void emitAsyncIteratorCloseSlow(
+      ESTree::Node *astNode,
       IteratorRecordSlow iteratorRecord,
       bool ignoreInnerException);