本文详解 emscripten 中因 asyncify 机制限制导致“cannot have multiple async operations in flight at once”崩溃的根本原因，并提供禁用 embind 自动异步包装、手动控制执行流等安全可靠的解决方案。
本文详解 emscripten 中因 asyncify 机制限制导致“cannot have multiple async operations in flight at once”崩溃的根本原因，并提供禁用 embind 自动异步包装、手动控制执行流等安全可靠的解决方案。
在使用 Emscripten 将 C++ 代码编译为 WebAssembly 并与 JavaScript 交互时，若启用了 ASYNCIFY（例如通过 -sASYNCIFY 编译选项），Emscripten 会自动注入 Asyncify 运行时以支持 C++ 中的“假同步阻塞调用”（如 emscripten_sleep、malloc 在某些场景下的挂起等）。然而，该机制会对所有 Embind 绑定函数无差别地添加异步包装层——即使 C++ 函数本身是纯同步的（如示例中的 sync_func()），它也可能被 Asyncify 视为潜在可挂起点，从而在 JS 回调中引发并发异步操作冲突。
典型崩溃复现逻辑如下：
- JS 传入一个 async 回调给 C++；
- C++ 异步触发该回调（如 func().await()）；
- 回调内部同时发起一个原生异步操作（如 fetch()）和一个同步 C++ 调用（如 Module.sync_func()）；
- 此时 Asyncify 检测到 fetch().then() 和 sync_func() 的底层 Asyncify 唤醒路径并行激活，触发断言失败：
RuntimeError: Aborted(Assertion failed: Cannot have multiple async operations in flight at once)。
⚠️ 关键认知：该错误并非源于 JS 代码逻辑错误，而是 Asyncify 运行时对“异步飞行中操作数”（in-flight async operations）的硬性单例限制 —— 它设计上只允许一个 Asyncify 挂起/恢复周期处于活跃状态。
✅ 推荐解决方案：显式解除 Embind 的 Asyncify 包装
最稳定、可控的方式是避免让 Asyncify 干预 Embind 函数调用流。可通过以下 EM_ASM 注入方式，在运行时劫持 Asyncify 的调度钩子：
// 在 Module 初始化前或 onRuntimeInitialized 中执行
EM_ASM(
if (Asyncify && Asyncify.whenDone) {
// 替换默认的 whenDone 行为：不再等待 Asyncify 恢复，直接 resolve
Asyncify.whenDone = () => Promise.resolve();
}
);? 原理说明：Asyncify.whenDone 是 Asyncify 内部用于协调异步边界的关键 Promise 钩子。将其重写为立即 resolve，可有效“短路”EmbBind 函数的自动异步封装，使 sync_func() 等调用回归纯同步语义，从而与 fetch() 等原生异步操作和平共存。
完整修复后的 JS 示例：
<html>
<body>
<script src="./out/build/em-x64-debug/async_test.js"></script>
<script>
// 关键：在模块加载前或初始化时禁用 Embind 的 Asyncify 包装
Module['onRuntimeInitialized'] = () => {
// 注入运行时补丁
Module._emscripten_asm_const_int('Asyncify.whenDone = () => Promise.resolve();');
// 或更兼容写法（适用于较新 Emscripten）
Module.addOnPreRun(() => {
Module._emscripten_asm_const_int('if (Asyncify && Asyncify.whenDone) Asyncify.whenDone = () => Promise.resolve();');
});
// 现在可安全混合调用
async function async_cb() {
await fetch('./test.txt'); // 原生异步
Module.sync_func(); // 同步 C++ 调用（已脱离 Asyncify 干预）
console.log('✅ Both calls succeeded.');
}
Module.async_func(async_cb);
};
</script>
</body>
</html>⚠️ 注意事项与替代建议
- 慎用 ASYNCIFY 全局启用：除非项目明确依赖 C++ 层的同步阻塞语义（如移植旧有 pthread 程序），否则建议优先通过 Asyncify 的细粒度白名单（-sASYNCIFY_IMPORTS=['func1','func2']）控制仅包装必要函数，而非全局开启。
- 避免 await + 同步调用的嵌套陷阱：即使打补丁后 sync_func() 变为真正同步，也请确保其内部不隐式触发任何 Asyncify 操作（如调用其他被 Asyncify 包装的函数），否则仍可能触发竞争。
- 长期演进方向：迁移到 Wasm GC / WASI-threads（未来）：Asyncify 是过渡性技术，性能开销大且行为隐蔽。Emscripten 2.0.30+ 已支持 --no-asyncify 默认关闭，配合 emrun --no-asyncify 可彻底规避该问题；对于新项目，推荐采用 Promise-based 主动异步接口设计，由 JS 控制流程，C++ 仅暴露非阻塞 API。
通过精准干预 Asyncify 的调度行为，开发者可在保留现有代码结构的前提下，安全实现 JS 异步逻辑与 C++ 同步函数的协同调用——这既是底层机制理解的体现，也是 WebAssembly 工程实践中关键的调试能力。
