From ef099f0c93b4a104a1f4c8e58d59d115c17308f8 Mon Sep 17 00:00:00 2001
From: Haled Odat <8566042+HalidOdat@users.noreply.github.com>
Date: Thu, 27 Jul 2023 23:21:23 +0200
Subject: [PATCH] Add code doc

---
 boa_engine/src/bytecompiler/declarations.rs |  8 -----
 boa_engine/src/bytecompiler/function.rs     | 39 ++++++++++++++++++++-
 boa_engine/src/bytecompiler/jump_control.rs |  9 +++++
 boa_engine/src/bytecompiler/mod.rs          |  4 +++
 boa_engine/src/vm/mod.rs                    |  2 --
 5 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/boa_engine/src/bytecompiler/declarations.rs b/boa_engine/src/bytecompiler/declarations.rs
index 6353370708b..dc4ae66241f 100644
--- a/boa_engine/src/bytecompiler/declarations.rs
+++ b/boa_engine/src/bytecompiler/declarations.rs
@@ -805,11 +805,6 @@ impl ByteCompiler<'_, '_> {
         strict: bool,
         generator: bool,
     ) -> (Option<Label>, bool) {
-        if self.in_async() && !self.in_generator() {
-            self.emit_opcode(Opcode::CreatePromiseCapability);
-            self.async_handler = Some(self.push_handler());
-        }
-
         let mut env_label = None;
         let mut additional_env = false;
 
@@ -1016,9 +1011,6 @@ impl ByteCompiler<'_, '_> {
             self.emit_opcode(Opcode::RestParameterPop);
         }
 
-        if self.async_handler.is_none() && self.in_async() {
-            self.async_handler = Some(self.push_handler());
-        }
         if generator {
             self.emit_opcode(Opcode::Generator);
             self.emit_u8(self.in_async().into());
diff --git a/boa_engine/src/bytecompiler/function.rs b/boa_engine/src/bytecompiler/function.rs
index 9ceffde0075..5418488d3f3 100644
--- a/boa_engine/src/bytecompiler/function.rs
+++ b/boa_engine/src/bytecompiler/function.rs
@@ -4,7 +4,7 @@ use crate::{
     builtins::function::ThisMode,
     bytecompiler::ByteCompiler,
     environments::CompileTimeEnvironment,
-    vm::{CodeBlock, CodeBlockFlags},
+    vm::{CodeBlock, CodeBlockFlags, Opcode},
     Context,
 };
 use boa_ast::function::{FormalParameterList, FunctionBody};
@@ -120,6 +120,31 @@ impl FunctionCompiler {
         // Function environment
         compiler.push_compile_environment(true);
 
+        // Taken from:
+        //  - 15.9.3 Runtime Semantics: EvaluateAsyncConciseBody: <https://tc39.es/ecma262/#sec-runtime-semantics-evaluateasyncconcisebody>
+        //  - 15.8.4 Runtime Semantics: EvaluateAsyncFunctionBody: <https://tc39.es/ecma262/#sec-runtime-semantics-evaluateasyncfunctionbody>
+        //
+        // Note: In `EvaluateAsyncGeneratorBody` unlike the async non-generator functions we don't handle exceptions thrown by
+        // `FunctionDeclarationInstantiation` (so they are propagated).
+        //
+        // See: 15.6.2 Runtime Semantics: EvaluateAsyncGeneratorBody: https://tc39.es/ecma262/#sec-runtime-semantics-evaluateasyncgeneratorbody
+        if compiler.in_async() && !compiler.in_generator() {
+            // 1. Let promiseCapability be ! NewPromiseCapability(%Promise%).
+            //
+            // Note: If the promise capability is already set, then we do nothing.
+            // This is a deviation from the spec, but it allows to set the promise capability by
+            // ExecuteAsyncModule ( module ): <https://tc39.es/ecma262/#sec-execute-async-module>
+            compiler.emit_opcode(Opcode::CreatePromiseCapability);
+
+            // 2. Let declResult be Completion(FunctionDeclarationInstantiation(functionObject, argumentsList)).
+            //
+            // Note: We push an exception handler so we catch exceptions that are thrown by the
+            // `FunctionDeclarationInstantiation` abstract function.
+            //
+            // Patched in `ByteCompiler::finish()`.
+            compiler.async_handler = Some(compiler.push_handler());
+        }
+
         let (env_label, additional_env) = compiler.function_declaration_instantiation(
             body,
             parameters,
@@ -128,6 +153,18 @@ impl FunctionCompiler {
             self.generator,
         );
 
+        // Taken from:
+        // - 27.6.3.2 AsyncGeneratorStart ( generator, generatorBody ): <https://tc39.es/ecma262/#sec-asyncgeneratorstart>
+        //
+        // Note: We do handle exceptions thrown by generator body in `AsyncGeneratorStart`.
+        if compiler.in_generator() {
+            assert!(compiler.async_handler.is_none());
+            if compiler.in_async() {
+                // Patched in `ByteCompiler::finish()`.
+                compiler.async_handler = Some(compiler.push_handler());
+            }
+        }
+
         compiler.compile_statement_list(body.statements(), false, false);
 
         if let Some(env_labels) = env_label {
diff --git a/boa_engine/src/bytecompiler/jump_control.rs b/boa_engine/src/bytecompiler/jump_control.rs
index ff3d862cb61..f98191386af 100644
--- a/boa_engine/src/bytecompiler/jump_control.rs
+++ b/boa_engine/src/bytecompiler/jump_control.rs
@@ -124,7 +124,16 @@ impl JumpRecord {
             JumpRecordKind::Continue => compiler.patch_jump_with_target(self.label, start_address),
             JumpRecordKind::Return => {
                 match (compiler.in_async(), compiler.in_generator()) {
+                    // Taken from:
+                    //  - 27.6.3.2 AsyncGeneratorStart ( generator, generatorBody ): https://tc39.es/ecma262/#sec-asyncgeneratorstart
+                    //
+                    // Note: If we are returning we have to close the async generator function.
                     (true, true) => compiler.emit_opcode(Opcode::AsyncGeneratorClose),
+
+                    // Taken from:
+                    //  - 27.7.5.2 AsyncBlockStart ( promiseCapability, asyncBody, asyncContext ): <https://tc39.es/ecma262/#sec-asyncblockstart>
+                    //
+                    // Note: If there is promise capability resolve or reject it based on pending exception.
                     (true, false) => compiler.emit_opcode(Opcode::CompletePromiseCapability),
                     (_, _) => {}
                 }
diff --git a/boa_engine/src/bytecompiler/mod.rs b/boa_engine/src/bytecompiler/mod.rs
index 0927f477ee9..f10e050082f 100644
--- a/boa_engine/src/bytecompiler/mod.rs
+++ b/boa_engine/src/bytecompiler/mod.rs
@@ -257,6 +257,10 @@ pub struct ByteCompiler<'ctx, 'host> {
     jump_info: Vec<JumpControlInfo>,
     pub(crate) in_async: bool,
     in_generator: bool,
+
+    /// Used to handle exception throws that escape the async function types.
+    ///
+    /// Async functions and async generator functions, need to be closed and resolved.
     pub(crate) async_handler: Option<u32>,
     json_parse: bool,
 
diff --git a/boa_engine/src/vm/mod.rs b/boa_engine/src/vm/mod.rs
index e11bd3217b7..c669dd97a48 100644
--- a/boa_engine/src/vm/mod.rs
+++ b/boa_engine/src/vm/mod.rs
@@ -199,7 +199,6 @@ impl Context<'_> {
     const OPERAND_COLUMN_WIDTH: usize = Self::COLUMN_WIDTH;
     const NUMBER_OF_COLUMNS: usize = 4;
 
-    #[inline(never)]
     fn trace_call_frame(&self) {
         let msg = if self.vm.frames.last().is_some() {
             format!(
@@ -232,7 +231,6 @@ impl Context<'_> {
         );
     }
 
-    #[inline(never)]
     fn trace_execute_instruction(&mut self) -> JsResult<CompletionType> {
         let mut pc = self.vm.frame().pc as usize;
         let opcode: Opcode = self.vm.frame().code_block.read::<u8>(pc).into();