Adding upstream version 124.0.1.upstream/124.0.1

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

1 files changed, 328 insertions, 0 deletions

diff --git a/js/src/vm/AsyncFunction.h b/js/src/vm/AsyncFunction.h
new file mode 100644
index 0000000000..8e31450f06
--- /dev/null
+++ b/js/src/vm/AsyncFunction.h
@@ -0,0 +1,328 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: set ts=8 sts=2 et sw=2 tw=80:
+ * 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/. */
+
+#ifndef vm_AsyncFunction_h
+#define vm_AsyncFunction_h
+
+#include "js/Class.h"
+#include "vm/GeneratorObject.h"
+#include "vm/JSObject.h"
+#include "vm/PromiseObject.h"
+
+// [SMDOC] Async functions
+//
+// # Implementation
+//
+// Async functions are implemented based on generators, in terms of
+// suspend/resume.
+// Instead of returning the generator object itself, they return the async
+// function's result promise to the caller.
+//
+// The async function's result promise is stored in the generator object
+// (js::AsyncFunctionGeneratorObject) and retrieved from it whenever the
+// execution needs it.
+//
+//
+// # Start
+//
+// When an async function is called, it synchronously runs until the first
+// `await` or `return`.  This works just like a normal function.
+//
+// This corresponds to steps 1-3, 5-9 of AsyncFunctionStart.
+//
+// AsyncFunctionStart ( promiseCapability, asyncFunctionBody )
+// https://tc39.es/ecma262/#sec-async-functions-abstract-operations-async-function-start
+//
+//   1. Let runningContext be the running execution context.
+//   2. Let asyncContext be a copy of runningContext.
+//   3. NOTE: Copying the execution state is required for the step below to
+//      resume its execution. It is ill-defined to resume a currently executing
+//      context.
+//   ...
+//   5. Push asyncContext onto the execution context stack; asyncContext is now
+//      the running execution context.
+//   6. Resume the suspended evaluation of asyncContext. Let result be the value
+//      returned by the resumed computation.
+//   7. Assert: When we return here, asyncContext has already been removed from
+//      the execution context stack and runningContext is the currently running
+//      execution context.
+//   8. Assert: result is a normal completion with a value of undefined. The
+//      possible sources of completion values are Await or, if the async
+//      function doesn't await anything, step 4.g above.
+//   9. Return.
+//
+// Unlike generators, async functions don't contain JSOp::InitialYield and
+// don't suspend immediately when call.
+//
+//
+// # Return
+//
+// Explicit/implicit `return` is implemented with the following bytecode
+// sequence:
+//
+// ```
+//   GetAliasedVar ".generator"      # VALUE .generator
+//   AsyncResolve                    # PROMISE
+//   SetRval                         #
+//   GetAliasedVar ".generator"      # .generator
+//   FinalYieldRval                  #
+// ```
+//
+// JSOp::Resolve (js::AsyncFunctionResolve) resolves the current async
+// function's result promise. Then this sets it as the function's return value.
+// (The return value is observable if the caller is still on the stack--
+// that is, the async function is returning without ever awaiting.
+// Otherwise we're returning to the microtask loop, which ignores the
+// return value.)
+//
+// This corresponds to AsyncFunctionStart steps 4.a-e. 4.g.
+//
+//   4. Set the code evaluation state of asyncContext such that when evaluation
+//      is resumed for that execution context the following steps will be
+//      performed:
+//     a. Let result be the result of evaluating asyncFunctionBody.
+//     b. Assert: If we return here, the async function either threw an
+//        exception or performed an implicit or explicit return; all awaiting
+//        is done.
+//     c. Remove asyncContext from the execution context stack and restore the
+//        execution context that is at the top of the execution context stack as
+//        the running execution context.
+//     d. If result.[[Type]] is normal, then
+//       i. Perform
+//          ! Call(promiseCapability.[[Resolve]], undefined, «undefined»).
+//     e. Else if result.[[Type]] is return, then
+//       i. Perform
+//          ! Call(promiseCapability.[[Resolve]], undefined,
+//                 «result.[[Value]]»).
+//     ...
+//     g. Return.
+//
+//
+// # Throw
+//
+// The body part of an async function is enclosed by an implicit try-catch
+// block, to catch `throw` completion of the function body.
+//
+// If an exception is thrown by the function body, the catch block catches it
+// and rejects the async function's result promise.
+//
+// If there's an expression in parameters, the entire parameters part is also
+// enclosed by a separate implicit try-catch block.
+//
+// ```
+//   Try                             #
+//   (parameter expressions here)    #
+//   Goto BODY                       #
+//
+//   JumpTarget from try             #
+//   ExceptionAndStack               # EXCEPTION STACK
+//   GetAliasedVar ".generator"      # EXCEPTION STACK .generator
+//   AsyncReject                     # PROMISE
+//   SetRval                         #
+//   GetAliasedVar ".generator"      # .generator
+//   FinalYieldRval                  #
+//
+// BODY:
+//   JumpTarget                      #
+//   Try                             #
+//   (body here)                     #
+//
+//   JumpTarget from try             #
+//   ExceptionAndStack               # EXCEPTION STACK
+//   GetAliasedVar ".generator"      # EXCEPTION STACK .generator
+//   AsyncReject                     # PROMISE
+//   SetRval                         #
+//   GetAliasedVar ".generator"      # .generator
+//   FinalYieldRval                  #
+// ```
+//
+// This corresponds to AsyncFunctionStart steps 4.f-g.
+//
+//   4. ...
+//     f. Else,
+//       i. Assert: result.[[Type]] is throw.
+//       ii. Perform
+//           ! Call(promiseCapability.[[Reject]], undefined,
+//                  «result.[[Value]]»).
+//     g. Return.
+//
+//
+// # Await
+//
+// `await` is implemented with the following bytecode sequence:
+// (ignoring CanSkipAwait for now, see "Optimization for await" section)
+//
+// ```
+//   (operand here)                  # VALUE
+//   GetAliasedVar ".generator"      # VALUE .generator
+//   AsyncAwait                      # PROMISE
+//
+//   GetAliasedVar ".generator"      # PROMISE .generator
+//   Await 0                         # RVAL GENERATOR RESUMEKIND
+//
+//   AfterYield                      # RVAL GENERATOR RESUMEKIND
+//   CheckResumeKind                 # RVAL
+// ```
+//
+// JSOp::AsyncAwait corresponds to Await steps 1-9, and JSOp::Await corresponds
+// to Await steps 10-12 in the spec.
+//
+// See the next section for JSOp::CheckResumeKind.
+//
+// After them, the async function is suspended, and if this is the first await
+// in the execution, the async function's result promise is returned to the
+// caller.
+//
+// Await
+// https://tc39.es/ecma262/#await
+//
+//   1. Let asyncContext be the running execution context.
+//   2. Let promise be ? PromiseResolve(%Promise%, value).
+//   3. Let stepsFulfilled be the algorithm steps defined in Await Fulfilled
+//      Functions.
+//   4. Let onFulfilled be ! CreateBuiltinFunction(stepsFulfilled, «
+//      [[AsyncContext]] »).
+//   5. Set onFulfilled.[[AsyncContext]] to asyncContext.
+//   6. Let stepsRejected be the algorithm steps defined in Await Rejected
+//      Functions.
+//   7. Let onRejected be ! CreateBuiltinFunction(stepsRejected, «
+//      [[AsyncContext]] »).
+//   8. Set onRejected.[[AsyncContext]] to asyncContext.
+//   9. Perform ! PerformPromiseThen(promise, onFulfilled, onRejected).
+//   10. Remove asyncContext from the execution context stack and restore the
+//       execution context that is at the top of the execution context stack as
+//       the running execution context.
+//   11. Set the code evaluation state of asyncContext such that when evaluation
+//       is resumed with a Completion completion, the following steps of the
+//       algorithm that invoked Await will be performed, with completion
+//       available.
+//   12. Return.
+//   13. NOTE: This returns to the evaluation of the operation that had most
+//       previously resumed evaluation of asyncContext.
+//
+// (See comments above AsyncAwait and Await in js/src/vm/Opcodes.h for more
+//  details)
+//
+//
+// # Reaction jobs and resume after await
+//
+// When an async function performs `await` and the operand becomes settled, a
+// new reaction job for the operand is enqueued to the job queue.
+//
+// The reaction record for the job is marked as "this is for async function"
+// (see js::AsyncFunctionAwait), and handled specially in
+// js::PromiseReactionJob.
+//
+// When the await operand resolves (either with fulfillment or rejection),
+// the async function is resumed from the job queue, by calling
+// js::AsyncFunctionAwaitedFulfilled or js::AsyncFunctionAwaitedRejected
+// from js::AsyncFunctionPromiseReactionJob.
+//
+// The execution resumes from JSOp::AfterYield, with the resolved value
+// and the resume kind, either normal or throw, corresponds to fulfillment or
+// rejection, on the stack.
+//
+// The resume kind is handled by JSOp::CheckResumeKind after that.
+//
+// If the resume kind is normal (=fulfillment), the async function resumes
+// the execution with the resolved value as the result of `await`.
+//
+// If the resume kind is throw (=rejection), it throws the resolved value,
+// and it will be caught by the try-catch explained above.
+//
+//
+// # Optimization for await
+//
+// Suspending the execution and going into the embedding's job queue is slow
+// and hard to optimize.
+//
+// If the following conditions are met, we don't have to perform the above
+// but just use the await operand as the result of await.
+//
+//   1. The await operand is either non-promise or already-fulfilled promise,
+//      so that the result value is already known
+//   2. There's no jobs in the job queue,
+//      so that we don't have to perform other jobs before resuming from
+//      await
+//   3. Promise constructor/prototype are not modified,
+//      so that the optimization isn't visible to the user code
+//
+// This is implemented by the following bytecode sequence:
+//
+// ```
+//   (operand here)                  # VALUE
+//
+//   CanSkipAwait                    # VALUE, CAN_SKIP
+//   MaybeExtractAwaitValue          # VALUE_OR_RVAL, CAN_SKIP
+//   JumpIfTrue END                  # VALUE
+//
+//   JumpTarget                      # VALUE
+//   GetAliasedVar ".generator"      # VALUE .generator
+//   Await 0                         # RVAL GENERATOR RESUMEKIND
+//   AfterYield                      # RVAL GENERATOR RESUMEKIND
+//   CheckResumeKind                 # RVAL
+//
+// END:
+//   JumpTarget                      # RVAL
+// ```
+//
+// JSOp::CanSkipAwait checks the above conditions. MaybeExtractAwaitValue will
+// replace Value if it can be skipped, and then the await is jumped over.
+
+namespace js {
+
+class AsyncFunctionGeneratorObject;
+
+extern const JSClass AsyncFunctionClass;
+
+// Resume the async function when the `await` operand resolves.
+// Split into two functions depending on whether the awaited value was
+// fulfilled or rejected.
+[[nodiscard]] bool AsyncFunctionAwaitedFulfilled(
+    JSContext* cx, Handle<AsyncFunctionGeneratorObject*> generator,
+    HandleValue value);
+
+[[nodiscard]] bool AsyncFunctionAwaitedRejected(
+    JSContext* cx, Handle<AsyncFunctionGeneratorObject*> generator,
+    HandleValue reason);
+
+// Resolve the async function's promise object with the given value and then
+// return the promise object.
+JSObject* AsyncFunctionResolve(JSContext* cx,
+                               Handle<AsyncFunctionGeneratorObject*> generator,
+                               HandleValue value);
+
+// Reject the async function's promise object with the given value and then
+// return the promise object.
+JSObject* AsyncFunctionReject(JSContext* cx,
+                              Handle<AsyncFunctionGeneratorObject*> generator,
+                              HandleValue reason, HandleValue stack);
+
+class AsyncFunctionGeneratorObject : public AbstractGeneratorObject {
+ public:
+  enum {
+    PROMISE_SLOT = AbstractGeneratorObject::RESERVED_SLOTS,
+
+    RESERVED_SLOTS
+  };
+
+  static const JSClass class_;
+  static const JSClassOps classOps_;
+
+  static AsyncFunctionGeneratorObject* create(JSContext* cx,
+                                              HandleFunction asyncGen);
+
+  static AsyncFunctionGeneratorObject* create(JSContext* cx,
+                                              Handle<ModuleObject*> module);
+
+  PromiseObject* promise() {
+    return &getFixedSlot(PROMISE_SLOT).toObject().as<PromiseObject>();
+  }
+};
+
+}  // namespace js
+
+#endif /* vm_AsyncFunction_h */