Modernize dependency system with Promise-based run blockers by sbc100 · Pull Request #27028 · emscripten-core/emscripten

sbc100 · 2026-05-29T00:04:23Z

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).

The following (18) test expectation files were updated by
running the tests with --rebaseline:

codesize/test_codesize_cxx_ctors1.json: 151867 => 151979 [+112 bytes / +0.07%]
codesize/test_codesize_cxx_ctors2.json: 151270 => 151382 [+112 bytes / +0.07%]
codesize/test_codesize_cxx_except.json: 195760 => 195873 [+113 bytes / +0.06%]
codesize/test_codesize_cxx_except_wasm.json: 166991 => 167103 [+112 bytes / +0.07%]
codesize/test_codesize_cxx_except_wasm_legacy.json: 164875 => 164987 [+112 bytes / +0.07%]
codesize/test_codesize_cxx_lto.json: 120708 => 120820 [+112 bytes / +0.09%]
codesize/test_codesize_cxx_mangle.json: 262239 => 262352 [+113 bytes / +0.04%]
codesize/test_codesize_cxx_noexcept.json: 153867 => 153979 [+112 bytes / +0.07%]
codesize/test_codesize_cxx_wasmfs.json: 179724 => 179741 [+17 bytes / +0.01%]
test/codesize/test_codesize_file_preload.expected.js updated
codesize/test_codesize_file_preload.json: 23823 => 23697 [-126 bytes / -0.53%]
codesize/test_codesize_files_js_fs.json: 18247 => 18342 [+95 bytes / +0.52%]
codesize/test_codesize_hello_O0.json: 38598 => 38578 [-20 bytes / -0.05%]
codesize/test_codesize_hello_dylink.json: 44132 => 44228 [+96 bytes / +0.22%]
codesize/test_codesize_hello_dylink_all.json: 855885 => 855967 [+82 bytes / +0.01%]
test/codesize/test_codesize_minimal_O0.expected.js updated
codesize/test_codesize_minimal_O0.json: 19738 => 19658 [-80 bytes / -0.41%]
codesize/test_unoptimized_code_size.json: 176480 => 176351 [-129 bytes / -0.07%]

Average change: +0.02% (-0.53% - +0.52%)

sbc100 · 2026-05-29T00:30:29Z

I'm petty happy about this change. Its something I've tried to do over the years several times and always given up in the end. This time with gemini's help I was able to get to the end of it.

The legacy versions of this API are also still supported which is nice.

The monitorRunDependencies system also still works, although its kind of pain. I wonder if folks actually depend on this counter-based callback.

kripken

Interesting!

kripken · 2026-06-01T20:39:12Z

 var LibraryFetch = {
  $Fetch__postset: 'Fetch.init();',
-  $Fetch__deps: ['$HandleAllocator'],
+  $Fetch__deps: ['$HandleAllocator', '$addRunBlocker'],


Where is this used in the file?

kripken · 2026-06-01T20:40:11Z

+
+
+
+    var resolve;


Why is there so much whitespace here?

kripken · 2026-06-01T20:40:23Z

+    runDependencies--;
+
+
+


kripken · 2026-06-01T20:47:25Z


 #if MAIN_READS_PARAMS
-function run(args = programArgs) {
+async function run(args = programArgs) {


Does making this function async change the API from the user's point of view? I don't recall if we allow users to call it directly.

…ependencies Simplify the file packager and LZ4 loading code by leveraging modern async/await features. Previously, we tracked the loading of each individual preloaded file by adding and removing separate run dependencies (`fp ${name}`). This introduced complexity and extra boilerplate. Now, we make `loadPackage` and `processPackageData` async functions and directly `await` the preloading of each file (including running any preload plugins). The main package-level run dependency (`datafile_${name}`) is held until all files are fully processed and then removed. This reduces code complexity, eliminates the need for granular run dependencies, and reduces the generated JS code size by ~100 bytes. Split out from emscripten-core#27028

Simplify the file packager and LZ4 loading code by leveraging modern async/await features. Previously, we tracked the loading of each individual preloaded file by adding and removing separate run dependencies (`fp ${name}`). This introduced complexity and extra boilerplate. Now, we make `loadPackage` and `processPackageData` async functions and directly `await` the preloading of each file (including running any preload plugins). The main package-level run dependency (`datafile_${name}`) is held until all files are fully processed and then removed. This reduces code complexity, eliminates the need for granular run dependencies, and reduces the generated JS code size by ~100 bytes. Split out from #27028

…27075) When `WASM_ASYNC_COMPILATION` is enabled `createWasm` returns a promise. However we were not always waiting on this and instead using the `addRunDependency` system to block the running of main. This change simplifies things by always awaiting the promise when it exists. This is kind of a followup to #27059 and a pre-cursor to #27028 which is a much larger change. Comes with a nice little codesize saving too, since it avoid the whole `addRunDependency` in most simple programs.

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). The following (18) test expectation files were updated by running the tests with `--rebaseline`: ``` codesize/test_codesize_cxx_ctors1.json: 151867 => 151979 [+112 bytes / +0.07%] codesize/test_codesize_cxx_ctors2.json: 151270 => 151382 [+112 bytes / +0.07%] codesize/test_codesize_cxx_except.json: 195760 => 195873 [+113 bytes / +0.06%] codesize/test_codesize_cxx_except_wasm.json: 166991 => 167103 [+112 bytes / +0.07%] codesize/test_codesize_cxx_except_wasm_legacy.json: 164875 => 164987 [+112 bytes / +0.07%] codesize/test_codesize_cxx_lto.json: 120708 => 120820 [+112 bytes / +0.09%] codesize/test_codesize_cxx_mangle.json: 262239 => 262352 [+113 bytes / +0.04%] codesize/test_codesize_cxx_noexcept.json: 153867 => 153979 [+112 bytes / +0.07%] codesize/test_codesize_cxx_wasmfs.json: 179724 => 179741 [+17 bytes / +0.01%] test/codesize/test_codesize_file_preload.expected.js updated codesize/test_codesize_file_preload.json: 23823 => 23697 [-126 bytes / -0.53%] codesize/test_codesize_files_js_fs.json: 18247 => 18342 [+95 bytes / +0.52%] codesize/test_codesize_hello_O0.json: 38598 => 38578 [-20 bytes / -0.05%] codesize/test_codesize_hello_dylink.json: 44132 => 44228 [+96 bytes / +0.22%] codesize/test_codesize_hello_dylink_all.json: 855885 => 855967 [+82 bytes / +0.01%] test/codesize/test_codesize_minimal_O0.expected.js updated codesize/test_codesize_minimal_O0.json: 19738 => 19658 [-80 bytes / -0.41%] codesize/test_unoptimized_code_size.json: 176480 => 176351 [-129 bytes / -0.07%] Average change: +0.02% (-0.53% - +0.52%) ```

sbc100 · 2026-06-24T00:31:30Z

I think I found a simpler, more elegant, solution that does not involve changing any external APIs: #27171

sbc100 requested review from brendandahl and kripken May 29, 2026 00:04

sbc100 force-pushed the runBlockers branch from 0d0b9e9 to e21d309 Compare May 29, 2026 00:21

sbc100 requested a review from kleisauke May 29, 2026 00:28

sbc100 force-pushed the runBlockers branch 3 times, most recently from b0f8006 to b66f862 Compare May 29, 2026 05:55

kripken reviewed May 29, 2026

View reviewed changes

sbc100 force-pushed the runBlockers branch from b66f862 to 7d4860e Compare May 29, 2026 21:37

sbc100 mentioned this pull request May 29, 2026

Make more use of async/await for file packging #27034

Merged

kripken reviewed May 29, 2026

View reviewed changes

Comment thread test/codesize/test_codesize_file_preload.expected.js Outdated

kripken reviewed May 29, 2026

View reviewed changes

Comment thread test/codesize/test_codesize_file_preload.json

sbc100 force-pushed the runBlockers branch from 7d4860e to e6aa25a Compare May 29, 2026 23:22

kripken reviewed Jun 1, 2026

View reviewed changes

sbc100 mentioned this pull request Jun 9, 2026

Always await the createWasm promise under WASM_ASYNC_COMPILATION #27075

Merged

sbc100 force-pushed the runBlockers branch from e6aa25a to 705cb47 Compare June 23, 2026 18:19

sbc100 force-pushed the runBlockers branch from 705cb47 to 09b1d2f Compare June 23, 2026 18:20

sbc100 closed this Jun 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modernize dependency system with Promise-based run blockers#27028

Modernize dependency system with Promise-based run blockers#27028
sbc100 wants to merge 1 commit into
emscripten-core:mainfrom
sbc100:runBlockers

sbc100 commented May 29, 2026 •

edited

Loading

Uh oh!

sbc100 commented May 29, 2026

Uh oh!

kripken left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kripken Jun 1, 2026

Uh oh!

kripken Jun 1, 2026

Uh oh!

kripken Jun 1, 2026

Uh oh!

kripken Jun 1, 2026

Uh oh!

sbc100 commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sbc100 commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sbc100 commented May 29, 2026

Uh oh!

kripken left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kripken Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kripken Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kripken Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

kripken Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

sbc100 commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sbc100 commented May 29, 2026 •

edited

Loading