Skip to content

Add emscripten_queue_microtask() API #25741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+46 −0
Open

Add emscripten_queue_microtask() API #25741

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
91daa78
Add emscripten_queue_microtask() API to enable use case described in …
juj Nov 7, 2025
5b6c25d
fix sig
juj Nov 7, 2025
27918d7
review
juj Nov 8, 2025
d18fa99
fix sig
juj Nov 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions ChangeLog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ See docs/process.md for more on how version tagging works.

4.0.20 (in development)
-----------------------
- Added new `emscripten_queue_microtask()` API to call the JS `queueMicrotask()`
function. (#25741)

4.0.19 - 11/04/25
-----------------
Expand Down
6 changes: 6 additions & 0 deletions src/lib/libhtml5.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2374,6 +2374,12 @@ var LibraryHTML5 = {
return requestAnimationFrame(tick);
},

emscripten_queue_microtask: (cb, userData) => {
queueMicrotask(() => {
{{{ makeDynCall('vp', 'cb') }}}(userData);
Copy link
Collaborator

@sbc100 sbc100 Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This probably needs to be wrapped in callUserCallback.

Copy link
Collaborator Author

@juj juj Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah.. Both the push and pop callback and callUserCallback are nice for some uses, but result in bloat :/

Added these, maybe callUserCallback() can be made zero-cost some day. (Or maybe it is so at least with Closure, not sure)

Copy link
Collaborator

@sbc100 sbc100 Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do need callUserCallback whenever we enter user code from the event loop otherwise lots of things can break. A classic one is calling exit() from within the callback.

IIRC the overhead of callUserCallback in MINIMAL_RUNTIME, where we don't have the same requirements is very close to zero. If you want to make reduce it to absolutely zero that seems like a good thing, but unrelated to this specific change.

});
},

emscripten_get_device_pixel_ratio__proxy: 'sync',
emscripten_get_device_pixel_ratio: () => {
#if ENVIRONMENT_MAY_BE_NODE || ENVIRONMENT_MAY_BE_SHELL
Expand Down
1 change: 1 addition & 0 deletions src/lib/libsigs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -731,6 +731,7 @@ sigs = {
emscripten_promise_race__sig: 'ppp',
emscripten_promise_resolve__sig: 'vpip',
emscripten_promise_then__sig: 'ppppp',
emscripten_queue_microtask__sig: 'ipp',
emscripten_random__sig: 'f',
emscripten_request_animation_frame__sig: 'ipp',
emscripten_request_animation_frame_loop__sig: 'vpp',
Expand Down
2 changes: 2 additions & 0 deletions system/include/emscripten/html5.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,8 @@ int emscripten_request_animation_frame(bool (*cb)(double time, void *userData),
void emscripten_cancel_animation_frame(int requestAnimationFrameId);
void emscripten_request_animation_frame_loop(bool (*cb)(double time, void *userData), void *userData);

void emscripten_queue_microtask(void (*cb)(void *userData), void *userData);
Copy link
Collaborator

@sbc100 sbc100 Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably go in emscripten/eventloop.h.


double emscripten_date_now(void);
double emscripten_performance_now(void);

Expand Down
25 changes: 25 additions & 0 deletions test/emscripten_queue_microtask.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
/*
* Copyright 2025 The Emscripten Authors. All rights reserved.
* Emscripten is available under two separate licenses, the MIT license and the
* University of Illinois/NCSA Open Source License. Both these licenses can be
* found in the LICENSE file.
*/

// Test emscripten_queue_microtask() behavior

#include <stdio.h>
#include <assert.h>
#include <emscripten.h>
#include <emscripten/html5.h>

void cb(void *userData) {
printf("cb\n");
assert(userData == (void*)42);
emscripten_force_exit(0);
}

int main() {
emscripten_queue_microtask(cb, (void*)42);
emscripten_exit_with_live_runtime();
return 99; // We won't reach here, but return non-zero value to guard against refactors that might exit() with this value.
}
7 changes: 7 additions & 0 deletions test/test_browser.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5016,6 +5016,13 @@ def test_emscripten_request_animation_frame_loop(self):
def test_request_animation_frame(self):
self.btest_exit('test_request_animation_frame.c')

def test_emscripten_queue_microtask(self):
self.btest_exit('emscripten_queue_microtask.c')

@requires_shared_array_buffer
def test_emscripten_queue_microtask_pthread(self):
Copy link
Collaborator

@sbc100 sbc100 Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other tests in this file do it this way:

  @parameterized({                                                                                 
    '': ([],),                                                                                     
    'proxy_to_pthread': (['-pthread', '-sPROXY_TO_PTHREAD'],),                                     
  })

Copy link
Collaborator Author

@juj juj Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason I didn't, was to get the @requires_shared_array_buffer annotation be precise.

Though now I remember I have a pthread magic regex catch for the same purpose, so changed to this form.

Copy link
Collaborator

@sbc100 sbc100 Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be consistent and use @parameterize everywhere.

There must be magic handling that injects @requires_shared_array_buffer I suppose? If you don't like that we could make a new @also_with_proxy_to_pthread that takes care of adding the cflags and also adding requires_shared_array_buffer.

self.btest_exit('emscripten_queue_microtask.c', cflags=['-pthread', '-sPROXY_TO_PTHREAD'])

@requires_shared_array_buffer
def test_emscripten_set_timeout(self):
self.btest_exit('emscripten_set_timeout.c', cflags=['-pthread', '-sPROXY_TO_PTHREAD'])
Expand Down
Loading