Simplify MODULARIZE code to always use async factory function (emscripten-core#24727)

The docs here were wrong. We have the `addRunDependency` system that can
delay module's readiness for an arbitrary amount of time, even if async
compilation is disabled.

This `addRunDependency` system does not exist in `MINUMAL_RUTTIME`, so
in some cases we can avoid the ready promise in `MINIMAL_RUNTIME` mode,
but that is a pretty subtle distinction that only applies to
`MINIMAL_RUNTIME`. Also even in this mode we were still marking the
factory function as async (note the lack of `USE_READY_PROMISE` in the
existing condition).

Author: sbc100

ChangeLog.md

@@ -20,6 +20,11 @@ See docs/process.md for more on how version tagging works.
 
 4.0.12 (in development)
 -----------------------
+- In `-sMODULARIZE` mode the factory function will now always return a promise,
+  even when `WASM_ASYNC_COMPILATION` is disabled.  This is because emscripten
+  has other features that might also return async module creation (e.g. loading
+  files over the network, or other users of the `addRunDependency` API).  For
+  consistency and simplicity we now *always* return a promise here. (#24727)
 - libcxx, libcxxabi, libunwind, and compiler-rt were updated to LLVM 20.1.8.
   (#24757)
 - The `fsblkcnt_t` and `fsfilcnt_t` types used by `statfs`/`statvfs` were

site/source/docs/tools_reference/settings_reference.rst

@@ -1863,14 +1863,9 @@ MODULARIZE
 By default we emit all code in a straightforward way into the output
 .js file. That means that if you load that in a script tag in a web
 page, it will use the global scope. With ``MODULARIZE`` set, we instead emit
-the code wrapped in a function that returns a promise. The promise is
-resolved with the module instance when it is safe to run the compiled code,
-similar to the ``onRuntimeInitialized`` callback. You do not need to use the
-``onRuntimeInitialized`` callback when using ``MODULARIZE``.
-
-(If WASM_ASYNC_COMPILATION is off, that is, if compilation is
-*synchronous*, then it would not make sense to return a Promise, and instead
-the Module object itself is returned, which is ready to be used.)
+the code wrapped in an async function. This function returns a promise that
+resolves to a module instance once it is safe to run the compiled code
+(similar to the ``onRuntimeInitialized`` callback).
 
 The default name of the function is ``Module``, but can be changed using the
 ``EXPORT_NAME`` option. We recommend renaming it to a more typical name for a

src/modularize.js

@@ -19,7 +19,7 @@ var {{{ EXPORT_NAME }}} = (() => {
   // after document.currentScript is gone, so we save it.
   // In EXPORT_ES6 mode we can just use 'import.meta.url'.
   var _scriptName = typeof document != 'undefined' ? document.currentScript?.src : undefined;
-  return {{{ asyncIf(WASM_ASYNC_COMPILATION || (EXPORT_ES6 && ENVIRONMENT_MAY_BE_NODE)) }}}function(moduleArg = {}) {
+  return async function(moduleArg = {}) {
     var moduleRtn;
 
 "<<< INNER_JS_CODE >>>"
@@ -30,7 +30,7 @@ var {{{ EXPORT_NAME }}} = (() => {
 #else
 // When targetting node and ES6 we use `await import ..` in the generated code
 // so the outer function needs to be marked as async.
-{{{ asyncIf(WASM_ASYNC_COMPILATION || (EXPORT_ES6 && ENVIRONMENT_MAY_BE_NODE)) }}}function {{{ EXPORT_NAME }}}(moduleArg = {}) {
+async function {{{ EXPORT_NAME }}}(moduleArg = {}) {
   var moduleRtn;
 
 "<<< INNER_JS_CODE >>>"

src/settings.js

@@ -1257,14 +1257,9 @@ var DETERMINISTIC = false;
 // By default we emit all code in a straightforward way into the output
 // .js file. That means that if you load that in a script tag in a web
 // page, it will use the global scope. With ``MODULARIZE`` set, we instead emit
-// the code wrapped in a function that returns a promise. The promise is
-// resolved with the module instance when it is safe to run the compiled code,
-// similar to the ``onRuntimeInitialized`` callback. You do not need to use the
-// ``onRuntimeInitialized`` callback when using ``MODULARIZE``.
-//
-// (If WASM_ASYNC_COMPILATION is off, that is, if compilation is
-// *synchronous*, then it would not make sense to return a Promise, and instead
-// the Module object itself is returned, which is ready to be used.)
+// the code wrapped in an async function. This function returns a promise that
+// resolves to a module instance once it is safe to run the compiled code
+// (similar to the ``onRuntimeInitialized`` callback).
 //
 // The default name of the function is ``Module``, but can be changed using the
 // ``EXPORT_NAME`` option. We recommend renaming it to a more typical name for a

test/test_other.py

@@ -7243,16 +7243,19 @@ def test_EXPORT_NAME_with_html(self):
     self.assertContained('error: customizing EXPORT_NAME requires that the HTML be customized to use that name', err)
 
   def test_modularize_sync_compilation(self):
+    # Verify that, even when WASM_ASYNC_COMPILATION is disabled, the module factory
+    # still returns a promise.   This behaviour was changed in #24727.
     create_file('post.js', r'''
 console.log('before');
 var result = Module();
 // It should be an object.
 console.log('typeof result: ' + typeof result);
-// And it should have the exports that Module has, showing it is Module in fact.
-console.log('typeof _main: ' + typeof result._main);
-// And it should not be a Promise.
 console.log('typeof result.then: ' + typeof result.then);
-console.log('after');
+result.then((inst) => {
+  // And it should have the exports that Module has, showing it is Module in fact.
+  console.log('typeof inst._main: ' + typeof inst._main);
+  console.log('after');
+});
 ''')
     self.run_process([EMCC, test_file('hello_world.c'),
                       '-sMODULARIZE',
@@ -7262,8 +7265,8 @@ def test_modularize_sync_compilation(self):
 before
 hello, world!
 typeof result: object
-typeof _main: function
-typeof result.then: undefined
+typeof result.then: function
+typeof inst._main: function
 after
 ''', self.run_js('a.out.js'))