Design: 提案：Async/Await JS API

该提案是与@fmccabe 、 @thibaudmichaud 、 @lukewagner和@kripken合作

该提案的目的是在 JavaScript promises 和 WebAssembly 之间提供相对高效且相对符合人体工程学的互操作，但在唯一的变化是对 JS API 而不是核心 wasm 的约束下工作。
期望堆栈切换提案最终将扩展核心 WebAssembly 的功能，以直接在 WebAssembly 中实现我们在本提案中提供的操作，以及许多其他有价值的堆栈切换操作，但是这个堆栈切换的特殊用例具有仅通过 JS API 就有足够的紧迫性来获得更快的路径。
有关更多信息，请参阅2021 年 6 月 28 日 Stack Subgroup Meeting的笔记和幻灯片，其中详细介绍了我们考虑的使用场景和因素，并总结了我们如何得出以下设计的基本原理。

更新：根据堆栈子组从 TC39 收到的反馈，该提案只允许暂停 WebAssembly 堆栈——它没有对 JavaScript 语言进行任何更改，特别是没有间接启用对分离的asycn / await在 JavaScript 中。

这（松散地）取决于js-types提案，它引入了WebAssembly.Function作为Function的子类。

界面

提议是将以下接口、构造函数和方法添加到 JS API，并在下面详细介绍它们的语义。

interface Suspender {
   constructor();
   Function suspendOnReturnedPromise(Function func); // import wrapper
   // overloaded: WebAssembly.Function suspendOnReturnedPromise(WebAssembly.Function func);
   WebAssembly.Function returnPromiseOnSuspend(WebAssembly.Function func); // export wrapper
}

例子

以下是我们希望人们如何使用此 API 的示例。
在我们的使用场景中，我们发现考虑 WebAssembly 模块在概念上具有“同步”和“异步”导入和导出是很有用的。
当前的 JS API 仅支持“同步”导入和导出。
Suspender 接口的方法用于包装相关的导入和导出以实现“异步”，而 Suspender 对象本身显式地将这些导入和导出连接在一起以促进实现和可组合性。

WebAssembly ( demo.wasm )：

(module
    (import "js" "init_state" (func $init_state (result f64)))
    (import "js" "compute_delta" (func $compute_delta (result f64)))
    (global $state f64)
    (func $init (global.set $state (call $init_state)))
    (start $init)
    (func $get_state (export "get_state") (result f64) (global.get $state))
    (func $update_state (export "update_state") (result f64)
      (global.set (f64.add (global.get $state) (call $compute_delta)))
      (global.get $state)
    )
)

文本（ data.txt ）：

19827.987

JavaScript：

var suspender = new Suspender();
var init_state = () => 2.71;
var compute_delta = () => fetch('data.txt').then(res => res.text()).then(txt => parseFloat(txt));
var importObj = {js: {
    init_state: init_state,
    compute_delta: suspender.suspendOnReturnedPromise(compute_delta)
}};

fetch('demo.wasm').then(response =>
    response.arrayBuffer()
).then(buffer =>
    WebAssembly.instantiate(buffer, importObj)
).then(({module, instance}) => {
    var get_state = instance.exports.get_state;
    var update_state = suspender.returnPromiseOnSuspend(instance.exports.update_state);
    ...
});

在这个例子中，我们有一个 WebAssembly 模块，它是一个非常简单的状态机——每次更新状态时，它只是调用一个导入来计算要添加到状态的增量。
然而，在 JavaScript 方面，我们想要用于计算 delta 的函数需要异步运行； 也就是说，它返回一个数字的承诺而不是数字本身。

我们可以通过使用新的 JS API 来弥合这种同步差距。
在示例中，WebAssembly 模块的导入使用suspender.suspendOnReturnedPromise包装，导出使用suspender.returnPromiseOnSuspend包装，两者都使用相同的suspender 。
suspender将两者连接在一起。
它使得，如果（未包装的）导入返回一个 Promise，（包装的）导出返回一个 Promise，中间的所有计算都被“暂停”，直到导入的 Promise 解决。
导出的包装本质上是添加一个async标记，而导入的包装本质上是添加一个await标记，但与 JavaScript 不同的是，我们不必显式线程化async / await贯穿所有中间 WebAssembly 函数！

同时，初始化时对init_state调用必然不挂起返回，而对export get_state调用也始终不挂起返回，所以提案仍然支持现有的“同步”导入和导出WebAssembly 生态系统今天使用。
当然，有很多细节被略过，例如如果同步导出调用异步导入，那么如果导入尝试挂起，程序就会陷入困境。
下面提供了更详细的规范以及一些实现策略。

规格

Suspender处于以下状态之一：

• 不活动- 目前未使用
• Active [ caller ] - 控件位于Suspender ， caller是调用Suspender并期待externref的函数
• 暂停- 目前正在等待一些承诺解决

方法suspender.returnPromiseOnSuspend(func)断言func是具有WebAssembly.Function形式的函数类型的[ti*] -> [to] ，然后返回具有函数类型的WebAssembly.Function [ti*] -> [externref]在使用参数args调用时执行以下操作：

1. 如果suspender的状态不是Inactive则陷阱
2. 将suspender的状态更改为Active [ caller ]（其中caller是当前调用者）
3. 让result成为调用func(args) （或任何陷阱或抛出的异常）的结果
4. 断言suspender的状态是Active [ caller' ] 一些caller' （应该保证，虽然调用者可能已经改变）
5. 将suspender的状态更改为Inactive
6. 返回（或重新抛出） result到caller'

方法suspender.suspendOnReturnedPromise(func)

• 如果func是WebAssembly.Function ，则断言其函数类型为[t*] -> [externref]并返回WebAssembly.Function函数类型[t*] -> [externref] ;
• 否则，断言func是Function并返回Function 。

在任何一种情况下， suspender.suspendOnReturnedPromise(func)返回的函数在使用参数args调用时都会执行以下操作：

1. 让result成为调用func(args) （或任何陷阱或抛出的异常）的结果
2. 如果result不是返回的 Promise，则返回（或重新抛出） result
3. 如果suspender的状态不是Active [ caller ] 一些caller陷阱
4. 让frames成为自caller以来的堆栈帧
5. 如果frames存在任何不可挂起函数的帧，则进行陷阱
6. 将suspender的状态更改为Suspended
7. 使用执行以下操作的函数onFulfilled和onRejected返回result.then(onFulfilled, onRejected)的结果：
   
   
   
   1. 断言suspender的状态是Suspended （应该保证）
   
   
   2. 将suspender的状态更改为Active [ caller' ]，其中caller'是onFulfilled / onRejected的调用者
   
   
   3. 
      
      
      • 在onFulfilled的情况下，将给定值转换为externref并将其返回给frames
      
      
      
      • 在onRejected的情况下，根据异常处理提案的 JS API 将给定值抛出高达frames作为异常
      
      
      
   
   

一个函数是可挂起的，如果它是

• 由 WebAssembly 模块定义，
• 由suspendOnReturnedPromise ，
• 由returnPromiseOnSuspend ，
• 或通过为可挂起函数创建宿主函数生成

重要的是，JavaScript 编写的函数不可挂起，符合TC39成员的反馈，宿主函数（除了上面列出的少数）不可挂起，符合引擎维护者的反馈。

执行

以下是该提案的实施策略。
它假设引擎支持堆栈切换，这当然是主要实现挑战所在。

有两种堆栈：主机（和 JavaScript）堆栈和 WebAssembly 堆栈。 每个 WebAssembly 堆栈都有一个名为suspender的 suspender 字段。 每个线程都有一个主机栈。

每个Suspender都有两个堆栈引用字段：一个称为caller ，另一个称为suspended 。

• 在Inactive状态下，两个字段都为空。
• 在Active状态下， caller字段引用调用者的（挂起）栈， suspended字段为空
• 在Suspended状态下， suspended字段引用当前与 suspender 关联的（暂停的）WebAssembly 堆栈， caller字段为空。

suspender.returnPromiseOnSuspend(func)(args)是由

1. 检查suspender.caller和suspended.suspended是否为空（否则捕获）
2. 让stack成为与suspender关联的新分配的 WebAssembly 堆栈
3. 切换到stack并将之前的堆栈存储在suspender.caller
4. 让result成为func(args) （或任何陷阱或抛出的异常）的结果
5. 切换到suspender.caller并将其设置为 null
6. 释放stack
7. 返回（或重新抛出） result

suspender.suspendOnReturnedPromise(func)(args)由

1. 调用func(args) ，捕获任何陷阱或抛出的异常
2. 如果result不是返回的 Promise，则返回（或重新抛出） result
3. 检查suspender.caller是否不为空（否则捕获）
4. 让stack成为当前堆栈
5. 虽然stack不是与suspender关联的 WebAssembly 堆栈：
   
   
   
   • 检查stack是否是一个 WebAssembly 堆栈（否则捕获）
   
   
   • 将stack更新stack.suspender.caller
   
   
6. 切换到suspender.caller ，将其设置为空，并将之前的堆栈存储在suspender.suspended
7. 使用函数onFulfilled和onRejected返回result.then(onFulfilled, onRejected)的结果
   
   
   
   1. 切换到suspender.suspended ，将其设置为 null，并将之前的堆栈存储在suspender.caller
   
   
   2. 
      
      
      • 在onFulfilled的情况下，将给定值转换为externref并返回它
      
      
      
      • 在onRejected的情况下，重新抛出给定的值
      
      
      
   
   

通过为可挂起函数创建宿主函数而生成的函数的实现更改为首先切换到当前线程的宿主堆栈（如果尚未在其上），最后切换回之前的堆栈。