emscripten-core / emscripten-core/emscripten
Consistent mapping of JS async APIs to native C/C++ APIs
- 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
Assessment
This issue has not been assessed yet.