Implements Promise-based API for modularized builds

emcc.py

@@ -1332,9 +1332,6 @@ def has_c_source(args):
 
     if shared.Settings.MODULARIZE:
       assert not options.proxy_to_worker, '-s MODULARIZE=1 and -s MODULARIZE_INSTANCE=1 are not compatible with --proxy-to-worker (if you want to run in a worker with -s MODULARIZE=1, you likely want to do the worker side setup manually)'
-      # MODULARIZE's .then() method uses onRuntimeInitialized currently, so make sure
-      # it is expected to be used.
-      shared.Settings.INCOMING_MODULE_JS_API += ['onRuntimeInitialized']
 
     if shared.Settings.EMULATE_FUNCTION_POINTER_CASTS:
       shared.Settings.ALIASING_FUNCTION_POINTERS = 0
@@ -3412,22 +3409,20 @@ def modularize():
   logger.debug('Modularizing, assigning to var ' + shared.Settings.EXPORT_NAME)
   src = open(final).read()
 
-  # TODO: exports object generation for MINIMAL_RUNTIME. As a temp measure, multithreaded MINIMAL_RUNTIME builds export like regular
-  # runtime does, so that worker.js can see the JS module contents.
-  exports_object = '{}' if shared.Settings.MINIMAL_RUNTIME and not shared.Settings.USE_PTHREADS else shared.Settings.EXPORT_NAME
-
   src = '''
 function(%(EXPORT_NAME)s) {
+  var returned_promise_resolve, returned_promise_reject;
+  var promise = new Promise(function(resolve, reject) { returned_promise_resolve=resolve, returned_promise_reject=reject; });
+
   %(EXPORT_NAME)s = %(EXPORT_NAME)s || {};
 
 %(src)s
 
-  return %(exports_object)s
+  return promise;
 }
 ''' % {
     'EXPORT_NAME': shared.Settings.EXPORT_NAME,
     'src': src,
-    'exports_object': exports_object
   }
 
   if not shared.Settings.MODULARIZE_INSTANCE:
@@ -3462,26 +3457,32 @@ def modularize():
         'src': src
       }
   else:
-    # Create the MODULARIZE_INSTANCE instance
-    # Note that we notice the global Module object, just like in normal
-    # non-MODULARIZE mode (while MODULARIZE has the user create the instances,
-    # and the user can decide whether to use Module there or something
-    # else etc.).
+    promise_variable_suffix = '_promise'
+    # Create the promise for the MODULARIZE_INSTANCE instance. The name of the
+    # variable will be `Module_promise` by default. If the EXPORT_NAME option
+    # is specified, the variable named will be `{EXPORT_NAME}_promise`.
+    #
+    # Note that the global, custom-named `Module` object is passed to the
+    # factory function invocation, just like in non-MODULARIZE mode. This is
+    # different than code built with the MODULARIZE option where the user
+    # specifies any Module seed when calling the factory function themselves.
     src = '''
-var %(EXPORT_NAME)s = (%(src)s)(typeof %(EXPORT_NAME)s === 'object' ? %(EXPORT_NAME)s : {});
+var %(EXPORT_NAME)s%(promise_variable_suffix)s = (%(src)s)(typeof %(EXPORT_NAME)s === 'object' ? %(EXPORT_NAME)s : {});
 ''' % {
       'EXPORT_NAME': shared.Settings.EXPORT_NAME,
-      'src': src
+      'src': src,
+      'promise_variable_suffix': promise_variable_suffix,
     }
 
   final = final + '.modular.js'
   with open(final, 'w') as f:
     f.write(src)
-
+    export_name = shared.Settings.EXPORT_NAME
+    if (shared.Settings.MODULARIZE_INSTANCE):
+      export_name += promise_variable_suffix
     # Export using a UMD style export, or ES6 exports if selected
-
     if shared.Settings.EXPORT_ES6:
-      f.write('''export default %s;''' % shared.Settings.EXPORT_NAME)
+      f.write('''export default %s;''' % export_name)
     elif not shared.Settings.MINIMAL_RUNTIME:
       f.write('''if (typeof exports === 'object' && typeof module === 'object')
       module.exports = %(EXPORT_NAME)s;
@@ -3490,7 +3491,7 @@ def modularize():
     else if (typeof exports === 'object')
       exports["%(EXPORT_NAME)s"] = %(EXPORT_NAME)s;
     ''' % {
-        'EXPORT_NAME': shared.Settings.EXPORT_NAME
+        'EXPORT_NAME': export_name
       })
 
   save_intermediate('modularized')

src/closure-externs/closure-externs.js

@@ -999,7 +999,6 @@ var noExitRuntime;
 //    https://github.com/google/closure-compiler/issues/3167
 var BigInt;
 
-
 // Worklet
 /**
  * @constructor
@@ -1069,4 +1068,12 @@ AudioWorkletNode.prototype.onprocessorerror;
 var registerProcessor = function(name, obj) {};
 var currentFrame;
 var currentTime;
-var sampleRate;
+var sampleRate;
+
+// These functions are declared in emcc.py but used in postamble.js; we need
+// to explicitly tell Closure Compiler about their existence since the
+// postamble is optimized independently
+/** @type {Function} */
+var returned_promise_resolve;
+/** @type {Function} */
+var returned_promise_reject;

src/postamble.js

@@ -68,7 +68,12 @@ if (memoryInitializer) {
     };
     var doBrowserLoad = function() {
       readAsync(memoryInitializer, applyMemoryInitializer, function() {
-        throw 'could not load memory initializer ' + memoryInitializer;
+        var e = new Error('could not load memory initializer ' + memoryInitializer);
+#if MODULARIZE
+          returned_promise_reject(e);
+#else
+          throw e;
+#endif
       });
     };
 #if SUPPORT_BASE64_EMBEDDING
@@ -121,36 +126,6 @@ if (memoryInitializer) {
 
 var calledRun;
 
-#if MODULARIZE
-#if MODULARIZE_INSTANCE == 0
-// Modularize mode returns a function, which can be called to
-// create instances. The instances provide a then() method,
-// must like a Promise, that receives a callback. The callback
-// is called when the module is ready to run, with the module
-// as a parameter. (Like a Promise, it also returns the module
-// so you can use the output of .then(..)).
-Module['then'] = function(func) {
-  // We may already be ready to run code at this time. if
-  // so, just queue a call to the callback.
-  if (calledRun) {
-    func(Module);
-  } else {
-    // we are not ready to call then() yet. we must call it
-    // at the same time we would call onRuntimeInitialized.
-#if ASSERTIONS && !expectToReceiveOnModule('onRuntimeInitialized')
-    abort('.then() requires adding onRuntimeInitialized to INCOMING_MODULE_JS_API');
-#endif
-    var old = Module['onRuntimeInitialized'];
-    Module['onRuntimeInitialized'] = function() {
-      if (old) old();
-      func(Module);
-    };
-  }
-  return Module;
-};
-#endif
-#endif
-
 /**
  * @constructor
  * @this {ExitStatus}
@@ -319,6 +294,9 @@ function run(args) {
 
     preMain();
 
+#if MODULARIZE
+    returned_promise_resolve(Module);
+#endif
 #if expectToReceiveOnModule('onRuntimeInitialized')
     if (Module['onRuntimeInitialized']) Module['onRuntimeInitialized']();
 #endif
@@ -429,9 +407,17 @@ function exit(status, implicit) {
     // if exit() was called, we may warn the user if the runtime isn't actually being shut down
     if (!implicit) {
 #if EXIT_RUNTIME == 0
-      err('program exited (with status: ' + status + '), but EXIT_RUNTIME is not set, so halting execution but not exiting the runtime or preventing further async execution (build with EXIT_RUNTIME=1, if you want a true shutdown)');
+      var msg = 'program exited (with status: ' + status + '), but EXIT_RUNTIME is not set, so halting execution but not exiting the runtime or preventing further async execution (build with EXIT_RUNTIME=1, if you want a true shutdown)';
+      err(msg);
+#if MODULARIZE
+      returned_promise_reject(msg);
+#endif // MODULARIZE
 #else
-      err('program exited (with status: ' + status + '), but noExitRuntime is set due to an async operation, so halting execution but not exiting the runtime or preventing further async execution (you can use emscripten_force_exit, if you want to force a true shutdown)');
+      var msg = 'program exited (with status: ' + status + '), but noExitRuntime is set due to an async operation, so halting execution but not exiting the runtime or preventing further async execution (you can use emscripten_force_exit, if you want to force a true shutdown)';
+      err(msg);
+#if MODULARIZE
+      returned_promise_reject(msg);
+#endif // MODULARIZE
 #endif // EXIT_RUNTIME
     }
 #endif // ASSERTIONS
@@ -484,15 +470,24 @@ if (!ENVIRONMENT_IS_PTHREAD) // EXIT_RUNTIME=0 only applies to default behavior
 #endif
 
 #if USE_PTHREADS
-if (!ENVIRONMENT_IS_PTHREAD) run();
+if (!ENVIRONMENT_IS_PTHREAD) {
+  run();
+} else {
 #if EMBIND
-else {  // Embind must initialize itself on all threads, as it generates support JS.
+  // Embind must initialize itself on all threads, as it generates support JS.
   Module['___embind_register_native_and_builtin_types']();
-}
 #endif // EMBIND
+#if MODULARIZE
+  // The promise resolve function typically gets called as part of the execution 
+  // of the Module `run`. The workers/pthreads don't execute `run` here, they
+  // call `run` in response to a message at a later time, so the creation
+  // promise can be resolved, marking the pthread-Module as initialized.
+  returned_promise_resolve(Module);
+#endif // MODULARIZE
+}
 #else
 run();
-#endif
+#endif // USE_PTHREADS
 
 #if BUILD_AS_WORKER
 

src/shell_minimal.js

@@ -131,6 +131,9 @@ function err(text) {
 // compilation is ready. In that callback, call the function run() to start
 // the program.
 function ready() {
+#if MODULARIZE
+  returned_promise_resolve(Module);
+#endif // MODULARIZE
 #if INVOKE_RUN && hasExportedFunction('_main')
 #if USE_PTHREADS
   if (!ENVIRONMENT_IS_PTHREAD) {

src/worker.js

@@ -109,7 +109,7 @@ this.onmessage = function(e) {
 #endif
 #else
       Module['wasmModule'] = e.data.wasmModule;
-#endif
+#endif // MINIMAL_RUNTIME
 
       {{{ makeAsmImportsAccessInPthread('wasmMemory') }}} = e.data.wasmMemory;
 
@@ -136,15 +136,17 @@ this.onmessage = function(e) {
       }
 #endif
 
-#endif
+#endif // WASM
 
 #if !MINIMAL_RUNTIME || MODULARIZE
       {{{ makeAsmImportsAccessInPthread('ENVIRONMENT_IS_PTHREAD') }}} = true;
 #endif
 
 #if MODULARIZE && EXPORT_ES6
       import(e.data.urlOrBlob).then(function({{{ EXPORT_NAME }}}) {
-        Module = {{{ EXPORT_NAME }}}.default(Module);
+        return {{{ EXPORT_NAME }}}.default(Module);
+      }).then(function(instance) {
+        Module = instance;
         postMessage({ 'cmd': 'loaded' });
       });
 #else
@@ -155,15 +157,28 @@ this.onmessage = function(e) {
         importScripts(objectUrl);
         URL.revokeObjectURL(objectUrl);
       }
-#if MODULARIZE && !MODULARIZE_INSTANCE
+#if MODULARIZE_INSTANCE
+      {{{ EXPORT_NAME }}}_promise.then(function (instance) {
+        Module = instance;
+        postMessage({ 'cmd': 'loaded' });
+      });
+#else
+#if MODULARIZE
 #if MINIMAL_RUNTIME
-      Module = {{{ EXPORT_NAME }}}(imports);
+      {{{ EXPORT_NAME }}}(imports).then(function (instance) {
+        Module = instance;
+        postMessage({ 'cmd': 'loaded' });
+      });
 #else
-      Module = {{{ EXPORT_NAME }}}(Module);
+      {{{ EXPORT_NAME }}}(Module).then(function (instance) {
+        Module = instance;
+        postMessage({ 'cmd': 'loaded' });
+      });
+#endif
 #endif
 #endif
 
-#if !MINIMAL_RUNTIME || !WASM
+#if !MODULARIZE && (!MINIMAL_RUNTIME || !WASM)
       // MINIMAL_RUNTIME always compiled Wasm (&Wasm2JS) asynchronously, even in pthreads. But
       // regular runtime and asm.js are loaded synchronously, so in those cases
       // we are now loaded, and can post back to main thread.

tests/code_size/hello_webgl2_fastcomp_asmjs.json

@@ -1,12 +1,12 @@
 {
   "a.html": 580,
   "a.html.gz": 382,
-  "a.js": 5322,
-  "a.js.gz": 2505,
+  "a.js": 5565,
+  "a.js.gz": 2577,
   "a.mem": 321,
   "a.mem.gz": 219,
-  "a.asm.js": 9778,
-  "a.asm.js.gz": 3528,
-  "total": 16001,
-  "total_gz": 6634
+  "a.asm.js": 9806,
+  "a.asm.js.gz": 3516,
+  "total": 16272,
+  "total_gz": 6694
 }

tests/code_size/hello_webgl2_fastcomp_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.html": 563,
   "a.html.gz": 377,
-  "a.js": 5288,
-  "a.js.gz": 2533,
-  "a.wasm": 7982,
-  "a.wasm.gz": 4368,
-  "total": 13833,
-  "total_gz": 7278
+  "a.js": 5531,
+  "a.js.gz": 2606,
+  "a.wasm": 7985,
+  "a.wasm.gz": 4411,
+  "total": 14079,
+  "total_gz": 7394
 }

tests/code_size/hello_webgl2_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.html": 563,
   "a.html.gz": 377,
-  "a.js": 5069,
-  "a.js.gz": 2418,
+  "a.js": 5312,
+  "a.js.gz": 2493,
   "a.wasm": 10894,
   "a.wasm.gz": 6920,
-  "total": 16526,
-  "total_gz": 9715
+  "total": 16769,
+  "total_gz": 9790
 }

tests/code_size/hello_webgl2_wasm2js.json

@@ -1,10 +1,10 @@
 {
   "a.html": 588,
   "a.html.gz": 386,
-  "a.js": 23671,
-  "a.js.gz": 8883,
+  "a.js": 23914,
+  "a.js.gz": 8966,
   "a.mem": 3168,
   "a.mem.gz": 2711,
-  "total": 27427,
-  "total_gz": 11980
+  "total": 27670,
+  "total_gz": 12063
 }

tests/code_size/hello_webgl_fastcomp_asmjs.json

@@ -1,12 +1,12 @@
 {
   "a.html": 580,
   "a.html.gz": 382,
-  "a.js": 4868,
-  "a.js.gz": 2350,
+  "a.js": 5111,
+  "a.js.gz": 2424,
   "a.mem": 321,
   "a.mem.gz": 219,
-  "a.asm.js": 9778,
-  "a.asm.js.gz": 3528,
-  "total": 15547,
-  "total_gz": 6479
+  "a.asm.js": 9806,
+  "a.asm.js.gz": 3516,
+  "total": 15818,
+  "total_gz": 6541
 }

tests/code_size/hello_webgl_fastcomp_wasm.json

@@ -1,10 +1,10 @@
 {
   "a.html": 563,
   "a.html.gz": 377,
-  "a.js": 4780,
-  "a.js.gz": 2356,
-  "a.wasm": 7982,
-  "a.wasm.gz": 4368,
-  "total": 13325,
-  "total_gz": 7101
+  "a.js": 5023,
+  "a.js.gz": 2432,
+  "a.wasm": 7985,
+  "a.wasm.gz": 4411,
+  "total": 13571,
+  "total_gz": 7220
 }