Modernize dependency system with Promise-based run blockers

Replace the callback-based dependenciesFulfilled/runDependencies system
with a modern async/await approach using "run blockers" (Promises).

This modernizes the startup sequence, ensuring preRun and other startup
hooks are executed exactly once by pausing and resuming execution flow
instead of re-running the entry point.

To maintain backward compatibility, a bridge is implemented for the
existing addRunDependency and removeRunDependency APIs, routing them
through the new Promise-based blocking mechanism.

- Make run() in postamble.js async to support await.
- Implement $addRunBlocker and $resolveRunBlockers in libcore.js.
- Bridge $addRunDependency and $removeRunDependency to use $addRunBlocker.
- Wrap runDependencies == 0 check in ASSERTIONS guard to avoid empty block in optimized builds (fixes Closure Compiler warnings).

Author: sbc100

ChangeLog.md

@@ -63,6 +63,12 @@ See docs/process.md for more on how version tagging works.
 - The `PThread.runningWorkers` field was removed from the `PThread` object.
   If you have JS code that was depending on this you can transition to using the
   `PThread.pthreads` object. (#26998)
+- Emscripten's startup dependency system was modernized to be promise-based.
+  These APIs are mostly internal.  The new API is called `addRunBlocker`. The
+  previous APIs (`addRunDependency`/`removeRunDependency`) still exist but are
+  deprecated. Internal subsystems (including Fetch, pthread pool seeding,
+  dylib preloading, LZ4 packages, and Filesystem preloading) have been
+  transitioned to use the new `addRunBlocker` API directly.
 
 5.0.7 - 04/30/26
 ----------------

site/source/docs/api_reference/emscripten.h.rst

@@ -327,7 +327,7 @@ Functions
 
   Asynchronously loads a script from a URL.
 
-  This integrates with the run dependencies system, so your script can call ``addRunDependency`` multiple times, prepare various asynchronous tasks, and call ``removeRunDependency`` on them; when all are complete (or if there were no run dependencies to begin with), ``onload`` is called. An example use for this is to load an asset module, that is, the output of the file packager.
+  This integrates with the run-blocker system, so your script can call ``addRunBlocker`` multiple times, with various asynchronous tasks (promises).  Only when all are complete will ``onload`` be called. An example use for this is to load an asset module, that is, the output of the file packager.
 
   This function is currently only available in main browser thread, and it will immediately fail by calling the supplied onerror() handler if called in a pthread.
 

site/source/docs/api_reference/preamble.js.rst

@@ -267,32 +267,22 @@ Conversion functions — strings, pointers and arrays
 
 
 
-Run dependencies
-================
-
-Note that generally run dependencies are managed by the file packager and other parts of the system. It is rare for developers to use this API directly.
-
-
-.. js:function:: addRunDependency(id)
+Run blockers (dependencies)
+===========================
 
-  Adds an ``id`` to the list of run dependencies.
+Note that generally run blockers are managed by the file packager and other internal systems. It is rare for developers to use this API directly.
 
-  This adds a run dependency and increments the run dependency counter.
+.. js:function:: addRunBlocker(promise)
 
-  .. COMMENT (not rendered): **HamishW** Remember to link to Execution lifecycle in Browser environment or otherwise link to information on using this. Possibly its own topic.
-
-  :param id: An arbitrary id representing the operation.
-  :type id: String
+  Adds a promise that must be resolved before the program starts running.
 
+.. js:function:: addRunDependency(id)
 
+  Deprecated: Use ``addRunBlocker`` instead
 
 .. js:function:: removeRunDependency(id)
 
-  Removes a specified ``id`` from the list of run dependencies.
-
-  :param id: The identifier for the specific dependency to be removed (added with :js:func:`addRunDependency`)
-  :type id: String
-
+  Deprecated: When using ``addRunBlocker``, there is no need to manually remove dependencies, just resolve the promise.
 
 
 Stack trace

site/source/docs/porting/emscripten-runtime-environment.rst

@@ -118,11 +118,11 @@ Execution lifecycle
 
 When an Emscripten-compiled application is loaded, it starts by preparing data in the ``preloading`` phase. Files you marked for :ref:`preloading <emcc-preload-file>` (using ``emcc --preload-file``, or manually from JavaScript with :js:func:`FS.createPreloadedFile`) are set up at this stage.
 
-You can add additional operations with :js:func:`addRunDependency`, which is a counter of all dependencies to be executed before compiled code can run. As these are completed you can call :js:func:`removeRunDependency` to remove the completed dependencies.
+You can add additional operations with :js:func:`addRunBlocker`, which takes a promise that will prevent your program's ``main()`` function from running until it is resolved.
 
 .. note:: Generally it is not necessary to add additional operations — preloading is suitable for almost all use cases.
 
-When all dependencies are met, Emscripten will call your programs's ``main()`` function. The ``main()`` function should be used to perform initialization tasks, and will often call :c:func:`emscripten_set_main_loop` (as :ref:`described above <emscripten-runtime-environment-howto-main-loop>`). The main loop function will be then be called at the requested frequency.
+When all the blockers are resolved, Emscripten will call your programs's ``main()`` function. The ``main()`` function should be used to perform initialization tasks, and will often call :c:func:`emscripten_set_main_loop` (as :ref:`described above <emscripten-runtime-environment-howto-main-loop>`). The main loop function will be then be called at the requested frequency.
 
 You can affect the operation of the main loop in several ways:
 

src/Fetch.js

@@ -292,28 +292,27 @@ var Fetch = {
   },
 #endif
 
-  async init() {
+  init() {
     Fetch.xhrs = new HandleAllocator();
 #if FETCH_SUPPORT_INDEXEDDB
 #if PTHREADS
     if (ENVIRONMENT_IS_PTHREAD) return;
 #endif
 
-    addRunDependency('library_fetch_init');
-    try {
-      var db = await Fetch.openDatabase('emscripten_filesystem', 1);
+    addRunBlocker((async () => {
+      try {
+        var db = await Fetch.openDatabase('emscripten_filesystem', 1);
 #if FETCH_DEBUG
-      dbg('fetch: IndexedDB successfully opened.');
+        dbg('fetch: IndexedDB successfully opened.');
 #endif
-      Fetch.dbInstance = db;
-    } catch (e) {
+        Fetch.dbInstance = db;
+      } catch (e) {
 #if FETCH_DEBUG
-      dbg('fetch: IndexedDB open failed.');
+        dbg('fetch: IndexedDB open failed.');
 #endif
-      Fetch.dbInstance = false;
-    } finally {
-      removeRunDependency('library_fetch_init');
-    }
+        Fetch.dbInstance = false;
+      }
+    })());
 #endif // ~FETCH_SUPPORT_INDEXEDDB
   }
 }

src/lib/libbrowser.js

@@ -614,7 +614,7 @@ var LibraryBrowser = {
   },
 
   // TODO: currently not callable from a pthread, but immediately calls onerror() if not on main thread.
-  emscripten_async_load_script__deps: ['$UTF8ToString'],
+  emscripten_async_load_script__deps: ['$UTF8ToString', '$resolveRunBlockers'],
   emscripten_async_load_script: async (url, onload, onerror) => {
     url = UTF8ToString(url);
 #if PTHREADS
@@ -624,20 +624,14 @@ var LibraryBrowser = {
       return;
     }
 #endif
-#if ASSERTIONS
-    assert(runDependencies === 0, 'async_load_script must be run when no other dependencies are active');
-#endif
+
     {{{ runtimeKeepalivePush() }}}
 
     var loadDone = () => {
       {{{ runtimeKeepalivePop() }}}
       if (onload) {
         var onloadCallback = () => callUserCallback({{{ makeDynCall('v', 'onload') }}});
-        if (runDependencies > 0) {
-          dependenciesFulfilled = onloadCallback;
-        } else {
-          onloadCallback();
-        }
+        resolveRunBlockers().then(onloadCallback);
       }
     }
 

src/lib/libcore.js

@@ -2246,126 +2246,50 @@ addToLibrary({
   $wasmMemory: 'memory',
 #endif
 
-  $getUniqueRunDependency: (id) => {
-#if ASSERTIONS
-    var orig = id;
-    while (1) {
-      if (!runDependencyTracking[id]) return id;
-      id = orig + Math.random();
-    }
-#else
-    return id;
-#endif
-  },
-
   $noExitRuntime__postset: () => addAtModule(makeModuleReceive('noExitRuntime')),
   $noExitRuntime: {{{ !EXIT_RUNTIME }}},
 
-#if !MINIMAL_RUNTIME
-  // A counter of dependencies for calling run(). If we need to
-  // do asynchronous work before running, increment this and
-  // decrement it. Incrementing must happen in a place like
-  // Module.preRun (used by emcc to add file preloading).
-  // Note that you can add dependencies in preRun, even though
-  // it happens right before run - run will be postponed until
-  // the dependencies are met.
-  $runDependencies__internal: true,
-  $runDependencies: 0,
-  // overridden to take different actions when all run dependencies are fulfilled
-  $dependenciesFulfilled__internal: true,
-  $dependenciesFulfilled: null,
-#if ASSERTIONS
-  $runDependencyTracking__internal: true,
-  $runDependencyTracking: {},
-  $runDependencyWatcher__internal: true,
-  $runDependencyWatcher: null,
+#if expectToReceiveOnModule('monitorRunDependencies')
+  $pendingRunBlockers__internal: true,
+  $pendingRunBlockers: 0,
 #endif
 
-  $addRunDependency__deps: ['$runDependencies', '$removeRunDependency',
-#if ASSERTIONS
-    '$runDependencyTracking',
-    '$runDependencyWatcher',
+  $runBlockers__internal: true,
+  $runBlockers: [],
+  $addRunBlocker__deps: ['$runBlockers', '$resolveRunBlockers',
+#if expectToReceiveOnModule('monitorRunDependencies')
+    '$pendingRunBlockers',
 #endif
   ],
-  $addRunDependency: (id) => {
-    runDependencies++;
-
+  $addRunBlocker: (promise) => {
 #if expectToReceiveOnModule('monitorRunDependencies')
-    Module['monitorRunDependencies']?.(runDependencies);
-#endif
-
-#if ASSERTIONS
-#if RUNTIME_DEBUG
-    dbg('addRunDependency', id);
-#endif
-    assert(id, 'addRunDependency requires an ID')
-    assert(!runDependencyTracking[id]);
-    runDependencyTracking[id] = 1;
-    if (runDependencyWatcher === null && globalThis.setInterval) {
-      // Check for missing dependencies every few seconds
-      runDependencyWatcher = setInterval(() => {
-        if (ABORT) {
-          clearInterval(runDependencyWatcher);
-          runDependencyWatcher = null;
-          return;
-        }
-        var shown = false;
-        for (var dep in runDependencyTracking) {
-          if (!shown) {
-            shown = true;
-            err('still waiting on run dependencies:');
-          }
-          err(`dependency: ${dep}`);
-        }
-        if (shown) {
-          err('(end of list)');
-        }
-      }, 10000);
-#if ENVIRONMENT_MAY_BE_NODE
-      // Prevent this timer from keeping the runtime alive if nothing
-      // else is.
-      runDependencyWatcher.unref?.()
-#endif
+    if (Module['monitorRunDependencies']) {
+      pendingRunBlockers++;
+      Module['monitorRunDependencies'](pendingRunBlockers);
+      var decrement = () => {
+        pendingRunBlockers--;
+        Module['monitorRunDependencies'](pendingRunBlockers);
+      };
+      var wrapped = promise.then(
+        (val) => { decrement(); return val; },
+        (err) => { decrement(); throw err; }
+      );
+      runBlockers.push(wrapped);
+      return;
     }
 #endif
+    runBlockers.push(promise);
   },
 
-  $removeRunDependency__deps: ['$runDependencies', '$dependenciesFulfilled',
-#if ASSERTIONS
-    '$runDependencyTracking',
-    '$runDependencyWatcher',
-#endif
-  ],
-  $removeRunDependency: (id) => {
-    runDependencies--;
-
-#if expectToReceiveOnModule('monitorRunDependencies')
-    Module['monitorRunDependencies']?.(runDependencies);
-#endif
-
-#if ASSERTIONS
-#if RUNTIME_DEBUG
-    dbg('removeRunDependency', id);
-#endif
-    assert(id, 'removeRunDependency requires an ID');
-    assert(runDependencyTracking[id]);
-    delete runDependencyTracking[id];
-#endif
-    if (runDependencies == 0) {
-#if ASSERTIONS
-      if (runDependencyWatcher !== null) {
-        clearInterval(runDependencyWatcher);
-        runDependencyWatcher = null;
-      }
-#endif
-      if (dependenciesFulfilled) {
-        var callback = dependenciesFulfilled;
-        dependenciesFulfilled = null;
-        callback(); // can add another dependenciesFulfilled
-      }
+  $resolveRunBlockers__internal: true,
+  $resolveRunBlockers__deps: ['$runBlockers'],
+  $resolveRunBlockers: async () => {
+    while (runBlockers.length) {
+      var current = runBlockers;
+      runBlockers = [];
+      await Promise.all(current);
     }
   },
-#endif
 
   // The following addOn<X> functions are for adding runtime callbacks at
   // various executions points. Each addOn<X> function has a corresponding

src/lib/libdylink.js

@@ -1235,8 +1235,8 @@ var LibraryDylink = {
   },
 
   $loadDylibs__internal: true,
-  $loadDylibs__deps: ['$loadDynamicLibrary', '$reportUndefinedSymbols', '$addRunDependency', '$removeRunDependency'],
-  $loadDylibs: async () => {
+  $loadDylibs__deps: ['$loadDynamicLibrary', '$reportUndefinedSymbols', '$addRunBlocker'],
+  $loadDylibs: () => {
     if (!dynamicLibraries.length) {
 #if DYLINK_DEBUG
       dbg('loadDylibs: no libraries to preload');
@@ -1248,19 +1248,17 @@ var LibraryDylink = {
 #if DYLINK_DEBUG
     dbg('loadDylibs:', dynamicLibraries);
 #endif
-    addRunDependency('loadDylibs');
-
-    // Load binaries asynchronously
-    for (var lib of dynamicLibraries) {
-      await loadDynamicLibrary(lib, {loadAsync: true, global: true, nodelete: true, allowUndefined: true})
-    }
-    // we got them all, wonderful
-    reportUndefinedSymbols();
-
+    addRunBlocker((async () => {
+      // Load binaries asynchronously
+      for (var lib of dynamicLibraries) {
+        await loadDynamicLibrary(lib, {loadAsync: true, global: true, nodelete: true, allowUndefined: true})
+      }
+      // we got them all, wonderful
+      reportUndefinedSymbols();
 #if DYLINK_DEBUG
-    dbg('loadDylibs done!');
+      dbg('loadDylibs done!');
 #endif
-    removeRunDependency('loadDylibs');
+    })());
   },
 
   // void* dlopen(const char* filename, int flags);

src/lib/libfetch.js

@@ -8,7 +8,7 @@
 
 var LibraryFetch = {
   $Fetch__postset: 'Fetch.init();',
-  $Fetch__deps: ['$HandleAllocator'],
+  $Fetch__deps: ['$HandleAllocator', '$addRunBlocker'],
   $Fetch: Fetch,
   _emscripten_fetch_get_response_headers_length__deps: ['$lengthBytesUTF8'],
   _emscripten_fetch_get_response_headers_length: fetchGetResponseHeadersLength,

src/lib/libfs_shared.js

@@ -54,19 +54,14 @@ addToLibrary({
     '$asyncLoad',
     '$PATH_FS',
     '$FS_createDataFile',
-    '$getUniqueRunDependency',
-    '$addRunDependency',
-    '$removeRunDependency',
+    '$addRunBlocker',
     '$FS_handledByPreloadPlugin',
   ],
-  $FS_preloadFile: async (parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish) => {
+  $FS_preloadFile: (parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish) => {
     // TODO we should allow people to just pass in a complete filename instead
     // of parent and name being that we just join them anyways
     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
-    addRunDependency(dep);
-
-    try {
+    var promise = (async () => {
       var byteArray = url;
       if (typeof url == 'string') {
         byteArray = await asyncLoad(url);
@@ -77,9 +72,9 @@ addToLibrary({
       if (!dontCreateFile) {
         FS_createDataFile(parent, name, byteArray, canRead, canWrite, canOwn);
       }
-    } finally {
-      removeRunDependency(dep);
-    }
+    })();
+    addRunBlocker(promise);
+    return promise;
   },
 #endif