Convert FS_handledByPreloadPlugin and plugin handle callback to async. (emscripten-core#24914)

sbc100 · web-flow · commit 43baa09d969e · 2025-08-12T17:05:41.000-07:00
The `FS_handledByPreloadPlugin` is completely internal so changing this
should be completely non-functional.

If external projects are implementing custom preload plugins they would
need to update their `handle` methods.  I've added an assertion in debug
builds to detect plugins that are not async.

This change will allow a followup which is to convert that whole file
preloading
mechanism to async.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -20,6 +20,10 @@ See docs/process.md for more on how version tagging works.
 
 4.0.13 (in development)
 -----------------------
+- The `handle` callback on the `preloadPlugins` used by `--use-preload-plugins`
+  (and `FS_createPreloadedFile` API`) was converted from callbacks to async.
+  Any externally managed plugins would need to be updated accordingly.  An
+  assertion will detect any such non-async plugins in the wild. (#24914)
 - SDL2 updated from 2.32.0 to 2.32.8. (#24912/)
 - `sdl-config` and `sdl2-config` scripts were simplified to avoid using python
   and the `.bat` file versions were removed, matching upstream SDL. (#24907)
diff --git a/src/lib/libbrowser.js b/src/lib/libbrowser.js
@@ -47,86 +47,90 @@ var LibraryBrowser = {
       imagePlugin['canHandle'] = function imagePlugin_canHandle(name) {
         return !Module['noImageDecoding'] && /\.(jpg|jpeg|png|bmp|webp)$/i.test(name);
       };
-      imagePlugin['handle'] = function imagePlugin_handle(byteArray, name, onload, onerror) {
+      imagePlugin['handle'] = async function imagePlugin_handle(byteArray, name) {
         var b = new Blob([byteArray], { type: Browser.getMimetype(name) });
         if (b.size !== byteArray.length) { // Safari bug #118630
           // Safari's Blob can only take an ArrayBuffer
           b = new Blob([(new Uint8Array(byteArray)).buffer], { type: Browser.getMimetype(name) });
         }
         var url = URL.createObjectURL(b);
-        var img = new Image();
-        img.onload = () => {
+        return new Promise((resolve, reject) => {
+          var img = new Image();
+          img.onload = () => {
 #if ASSERTIONS
-          assert(img.complete, `Image ${name} could not be decoded`);
+            assert(img.complete, `Image ${name} could not be decoded`);
 #endif
-          var canvas = /** @type {!HTMLCanvasElement} */ (document.createElement('canvas'));
-          canvas.width = img.width;
-          canvas.height = img.height;
-          var ctx = canvas.getContext('2d');
-          ctx.drawImage(img, 0, 0);
-          Browser.preloadedImages[name] = canvas;
-          URL.revokeObjectURL(url);
-          onload?.(byteArray);
-        };
-        img.onerror = (event) => {
-          err(`Image ${url} could not be decoded`);
-          onerror?.();
-        };
-        img.src = url;
+            var canvas = /** @type {!HTMLCanvasElement} */ (document.createElement('canvas'));
+            canvas.width = img.width;
+            canvas.height = img.height;
+            var ctx = canvas.getContext('2d');
+            ctx.drawImage(img, 0, 0);
+            Browser.preloadedImages[name] = canvas;
+            URL.revokeObjectURL(url);
+            resolve(byteArray);
+          };
+          img.onerror = (event) => {
+            err(`Image ${url} could not be decoded`);
+            reject();
+          };
+          img.src = url;
+        });
       };
       preloadPlugins.push(imagePlugin);
 
       var audioPlugin = {};
       audioPlugin['canHandle'] = function audioPlugin_canHandle(name) {
         return !Module['noAudioDecoding'] && name.slice(-4) in { '.ogg': 1, '.wav': 1, '.mp3': 1 };
       };
-      audioPlugin['handle'] = function audioPlugin_handle(byteArray, name, onload, onerror) {
-        var done = false;
-        function finish(audio) {
-          if (done) return;
-          done = true;
-          Browser.preloadedAudios[name] = audio;
-          onload?.(byteArray);
-        }
-        var b = new Blob([byteArray], { type: Browser.getMimetype(name) });
-        var url = URL.createObjectURL(b); // XXX we never revoke this!
-        var audio = new Audio();
-        audio.addEventListener('canplaythrough', () => finish(audio), false); // use addEventListener due to chromium bug 124926
-        audio.onerror = function audio_onerror(event) {
-          if (done) return;
-          err(`warning: browser could not fully decode audio ${name}, trying slower base64 approach`);
-          function encode64(data) {
-            var BASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-            var PAD = '=';
-            var ret = '';
-            var leftchar = 0;
-            var leftbits = 0;
-            for (var i = 0; i < data.length; i++) {
-              leftchar = (leftchar << 8) | data[i];
-              leftbits += 8;
-              while (leftbits >= 6) {
-                var curr = (leftchar >> (leftbits-6)) & 0x3f;
-                leftbits -= 6;
-                ret += BASE[curr];
+      audioPlugin['handle'] = async function audioPlugin_handle(byteArray, name) {
+        return new Promise((resolve, reject) => {
+          var done = false;
+          function finish(audio) {
+            if (done) return;
+            done = true;
+            Browser.preloadedAudios[name] = audio;
+            resolve(byteArray);
+          }
+          var b = new Blob([byteArray], { type: Browser.getMimetype(name) });
+          var url = URL.createObjectURL(b); // XXX we never revoke this!
+          var audio = new Audio();
+          audio.addEventListener('canplaythrough', () => finish(audio), false); // use addEventListener due to chromium bug 124926
+          audio.onerror = function audio_onerror(event) {
+            if (done) return;
+            err(`warning: browser could not fully decode audio ${name}, trying slower base64 approach`);
+            function encode64(data) {
+              var BASE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+              var PAD = '=';
+              var ret = '';
+              var leftchar = 0;
+              var leftbits = 0;
+              for (var i = 0; i < data.length; i++) {
+                leftchar = (leftchar << 8) | data[i];
+                leftbits += 8;
+                while (leftbits >= 6) {
+                  var curr = (leftchar >> (leftbits-6)) & 0x3f;
+                  leftbits -= 6;
+                  ret += BASE[curr];
+                }
               }
+              if (leftbits == 2) {
+                ret += BASE[(leftchar&3) << 4];
+                ret += PAD + PAD;
+              } else if (leftbits == 4) {
+                ret += BASE[(leftchar&0xf) << 2];
+                ret += PAD;
+              }
+              return ret;
             }
-            if (leftbits == 2) {
-              ret += BASE[(leftchar&3) << 4];
-              ret += PAD + PAD;
-            } else if (leftbits == 4) {
-              ret += BASE[(leftchar&0xf) << 2];
-              ret += PAD;
-            }
-            return ret;
-          }
-          audio.src = 'data:audio/x-' + name.slice(-3) + ';base64,' + encode64(byteArray);
-          finish(audio); // we don't wait for confirmation this worked - but it's worth trying
-        };
-        audio.src = url;
-        // workaround for chrome bug 124926 - we do not always get oncanplaythrough or onerror
-        safeSetTimeout(() => {
-          finish(audio); // try to use it even though it is not necessarily ready to play
-        }, 10000);
+            audio.src = 'data:audio/x-' + name.slice(-3) + ';base64,' + encode64(byteArray);
+            finish(audio); // we don't wait for confirmation this worked - but it's worth trying
+          };
+          audio.src = url;
+          // workaround for chrome bug 124926 - we do not always get oncanplaythrough or onerror
+          safeSetTimeout(() => {
+            finish(audio); // try to use it even though it is not necessarily ready to play
+          }, 10000);
+        });
       };
       preloadPlugins.push(audioPlugin);
 #endif
diff --git a/src/lib/libdylink.js b/src/lib/libdylink.js
@@ -21,24 +21,22 @@ var LibraryDylink = {
       'canHandle': (name) => {
         return !Module['noWasmDecoding'] && name.endsWith('.so')
       },
-      'handle': (byteArray, name, onload, onerror) => {
+      'handle': async (byteArray, name) =>
         // loadWebAssemblyModule can not load modules out-of-order, so rather
         // than just running the promises in parallel, this makes a chain of
         // promises to run in series.
-        wasmPlugin.promiseChainEnd = wasmPlugin.promiseChainEnd.then(
-          () => loadWebAssemblyModule(byteArray, {loadAsync: true, nodelete: true}, name, {})).then(
-            (exports) => {
+        wasmPlugin.promiseChainEnd = wasmPlugin.promiseChainEnd.then(async () => {
+          try {
+            var exports = await loadWebAssemblyModule(byteArray, {loadAsync: true, nodelete: true}, name, {});
+          } catch (error) {
+            throw new Error(`failed to instantiate wasm: ${name}: ${error}`);
+          }
 #if DYLINK_DEBUG
-              dbg('registering preloadedWasm:', name);
-#endif
-              preloadedWasm[name] = exports;
-              onload(byteArray);
-            },
-            (error) => {
-              err(`failed to instantiate wasm: ${name}: ${error}`);
-              onerror();
-            });
-      }
+          dbg('registering preloadedWasm:', name);
+#endif
+          preloadedWasm[name] = exports;
+          return byteArray;
+        })
     };
     preloadPlugins.push(wasmPlugin);
   },
diff --git a/src/lib/libfs_shared.js b/src/lib/libfs_shared.js
@@ -13,19 +13,23 @@ addToLibrary({
   // it was handled.
   $FS_handledByPreloadPlugin__internal: true,
   $FS_handledByPreloadPlugin__deps: ['$preloadPlugins'],
-  $FS_handledByPreloadPlugin: (byteArray, fullname, finish, onerror) => {
+  $FS_handledByPreloadPlugin: async (byteArray, fullname) => {
 #if LibraryManager.has('libbrowser.js')
     // Ensure plugins are ready.
     if (typeof Browser != 'undefined') Browser.init();
 #endif
 
     for (var plugin of preloadPlugins) {
       if (plugin['canHandle'](fullname)) {
-        plugin['handle'](byteArray, fullname, finish, onerror);
-        return true;
+#if ASSERTIONS
+        assert(plugin['handle'].constructor.name === 'AsyncFunction', 'Filesystem plugin handlers must be async functions (See #24914)')
+#endif
+        return plugin['handle'](byteArray, fullname);
       }
     }
-    return false;
+    // In no plugin handled this file then return the original/unmodified
+    // byteArray.
+    return byteArray;
   },
 
   // Preloads a file asynchronously. You can call this before run, for example in
@@ -53,21 +57,21 @@ addToLibrary({
     var fullname = name ? PATH_FS.resolve(PATH.join2(parent, name)) : parent;
     var dep = getUniqueRunDependency(`cp ${fullname}`); // might have several active requests for the same fullname
     function processData(byteArray) {
-      function finish(byteArray) {
-        preFinish?.();
-        if (!dontCreateFile) {
-          FS_createDataFile(parent, name, byteArray, canRead, canWrite, canOwn);
-        }
-        onload?.();
-        removeRunDependency(dep);
-      }
-      if (!FS_handledByPreloadPlugin(byteArray, fullname, finish, () => {
-        onerror?.();
-        removeRunDependency(dep);
-      })) {
-        finish(byteArray);
-      }
+      FS_handledByPreloadPlugin(byteArray, fullname)
+        .then((byteArray) => {
+          preFinish?.();
+          if (!dontCreateFile) {
+            FS_createDataFile(parent, name, byteArray, canRead, canWrite, canOwn);
+          }
+          onload?.();
+          removeRunDependency(dep);
+        })
+        .catch(() =>  {
+          onerror?.();
+          removeRunDependency(dep);
+        });
     }
+
     addRunDependency(dep);
     if (typeof url == 'string') {
       asyncLoad(url).then(processData, onerror);
diff --git a/src/lib/liblz4.js b/src/lib/liblz4.js
@@ -56,7 +56,10 @@ addToLibrary({
               addRunDependency(dep);
               var finish = () => removeRunDependency(dep);
               var byteArray = FS.readFile(fullname);
-              plugin['handle'](byteArray, fullname, finish, finish);
+#if ASSERTIONS
+              assert(plugin['handle'].constructor.name === 'AsyncFunction', 'Filesystem plugin handlers must be async functions (See #24914)')
+#endif
+              plugin['handle'](byteArray, fullname).then(finish).catch(finish);
               break;
             }
           }
diff --git a/test/code_size/test_codesize_hello_dylink.json b/test/code_size/test_codesize_hello_dylink.json
@@ -1,10 +1,10 @@
 {
-  "a.out.js": 26982,
-  "a.out.js.gz": 11461,
+  "a.out.js": 27008,
+  "a.out.js.gz": 11463,
   "a.out.nodebug.wasm": 18561,
   "a.out.nodebug.wasm.gz": 9167,
-  "total": 45543,
-  "total_gz": 20628,
+  "total": 45569,
+  "total_gz": 20630,
   "sent": [
     "__heap_base",
     "__indirect_function_table",
diff --git a/test/code_size/test_codesize_hello_dylink_all.json b/test/code_size/test_codesize_hello_dylink_all.json
@@ -1,7 +1,7 @@
 {
-  "a.out.js": 246799,
+  "a.out.js": 246873,
   "a.out.nodebug.wasm": 597826,
-  "total": 844625,
+  "total": 844699,
   "sent": [
     "IMG_Init",
     "IMG_Load",

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,10 @@ addToLibrary({`
`56`	`56`	`addRunDependency(dep);`
`57`	`57`	`var finish = () => removeRunDependency(dep);`
`58`	`58`	`var byteArray = FS.readFile(fullname);`
`59`		`- plugin['handle'](byteArray, fullname, finish, finish);`
	`59`	`+#if ASSERTIONS`
	`60`	`+ assert(plugin['handle'].constructor.name === 'AsyncFunction', 'Filesystem plugin handlers must be async functions (See #24914)')`
	`61`	`+#endif`
	`62`	`+ plugin['handle'](byteArray, fullname).then(finish).catch(finish);`
`60`	`63`	`break;`
`61`	`64`	`}`
`62`	`65`	`}`