emscripten-core / emscripten-core/emscripten

Consistent mapping of JS async APIs to native C/C++ APIs

Open
#21,440 19 comments 2 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
27.6k
Forks
3.6k
Avg merge
1d 1h
Merged PRs (30d)
105

Description

On the Web and in JS a lot APIs are async, and emscripten contains C/C++ interfaces to these APIs in several places that take several different forms.

1. APIs that take callback functions.
2. APIs that are blocking from a C/C++ POV but depend on ASYNCIFY to perform that async operation.
3. APIs return a C `promise_t` which is a reflation of a JS promise in native code.

It would be good if all APIs were available in all 3 flavors.

Additionally it would be good if APIs authors only needed to implement one of these flavors and the other two were automatically make available in terms of this single one.

TODO:

- [ ] Decide which flavor should be the canonical one
- [ ] Enumerate all current async APIs. (Create a bug for each of them?)
- [ ] Create tooling to provide different APIs flavors based on a single one
- [ ] Move all current APIs to this new mechanism

Async APIs in emscripten:

- [`emscripten_fetch`](https://github.com/emscripten-core/emscripten/blob/524b94f1040115355cedda92bcff240b7bcd4a2a/system/include/emscripten/fetch.h#L203-L214): Callback-based API with option to block with `emscripten_fetch_wait` when not on the main thread. Based on XMLHttpRequest under the hood, which it self is a callback-based API
- [`emscripten_wget`](https://github.com/emscripten-core/emscripten/blob/524b94f1040115355cedda92bcff240b7bcd4a2a/system/include/emscripten/wget.h): Callback-based API, with blocking version when `ASYNCIFY` is enabled. Based on `XMLHttpRequest` under the hood.
- [IDB API](https://github.com/emscripten-core/emscripten/blob/524b94f1040115355cedda92bcff240b7bcd4a2a/system/include/emscripten/emscripten.h#L90-L111): Contains both callback-based, and blocking `ASYNCIFY` versions of the API. Based on callback-based [IDBDatabase](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase) API under the hood.|
- [`emscripten_dlopen`](https://github.com/emscripten-core/emscripten/blob/524b94f1040115355cedda92bcff240b7bcd4a2a/system/include/emscripten/emscripten.h#L177-L185): Callback-based + promise-based version available. Based on promise internally.
- [`emscripten_async_load_script`](https://github.com/emscripten-core/emscripten/blob/524b94f1040115355cedda92bcff240b7bcd4a2a/system/include/emscripten/emscripten.h#L38-L39): Callback-based, and also callback-based under hood based on the the HTML scripte tag onload attribute.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.