Enable multiple backends supported by the api crate to be used in the c-api as well #5443

xdoardo · 2025-02-28T13:54:51Z

(fixes #5224)

This PR adds to the wasm_engine_t enum the kinds V8, WAMR, WASMI and JSC to reflect the different possible kinds of engine that can actually be used in the underlying implementation. These enum variants can be by users used as a means to set the wanted engine in the underlying implementation.
Together with this addition, this PR changes the wasm_config_t type to (internally) hold an engine-specific configuration:

pub struct wasm_config_t {
    pub(super) engine: wasmer_engine_t,
    pub(super) engine_config: wasmer_engine_config_t, <------
    ...
}

where wasmer_engine_config_t is an enumeration of all the configurations for all the available engines:

enum wasmer_engine_config_t {
    #[cfg(feature = "sys")]
    Sys(sys::wasmer_sys_engine_config_t),

    #[cfg(feature = "jsc")]
    Jsc(jsc::wasmer_jsc_engine_config_t),
    
    ...
}

The two separate fields are needed because one, wasmer_engine_t, is public and users can set it; the other is definitely private and users cannot interact directly with it. This PR also introduces the relevant features to enable each of the backends cited above, with the matching X-default features to chose one as default.

Note: this PR produces a number of breaking changes in the API. Most notably, functions that were implicitly tied to the sys engine only, are now scoped with the sys name: wasm_config_canonicalize_nans is now wasm_config_sys_canonicalize_nans. Same goes for wasm_config_set_sys_target (previously wasm_config_set_target), wasm_config_sys_push_middleware (previously wasm_config_push_middleware), and wasm_config_set_sys_compiler (previously wasm_config_set_compiler).

Furthermore, a chage in the semantics of these functions is (debatably) introduced: what does it mean to call wasm_config_sys_push_middleware on a config whose selected wasmer_engine_t is not sys? In this PR the introduced behaviour is that of regardlessly change the selected engine to sys:

pub extern "C" fn wasm_config_set_sys_compiler(
    config: &mut wasm_config_t,
    compiler: wasmer_compiler_t,
) {
    ... 
    config.engine = wasmer_engine_t::UNIVERSAL;
    ... 
}

On one hand, this behaviour is transparent to the user - which should nonetheless expect the underlying engine to be the sys one, while on the other this function does not return a value, so we can't signal the user that the an error occurred in the case the current config.engine != sys.

Notice, also, that to maintain a bit of backwards compatibility, the enum constructor in the wasmer_engine_t corresponding to sys is still UNIVERSAL.

Missing bits:

More tests with all the backends enabled
CI jobs to target those tests

…efault backend ... so that we don't have to build an engine to find out which engine is the default one per the enabled features.

promptless · 2025-02-28T13:56:02Z

📝 Documentation updates detected! A separate PR for documentation updates has been made here: wasmerio/docs.wasmer.io#118

syrusakbary · 2025-02-28T14:25:27Z

lib/api/src/backend/mod.rs

+
+impl Default for BackendKind {
+    fn default() -> Self {
+        #[cfg(feature = "sys-default")]


Can we make the features collide and show a compiler error if that's the case? (eg: you can't enable sys-default and wamr-default at the same time)

Yes, we already have this in the wasmer crate: https://github.com/wasmerio/wasmer/blob/main/lib/api/src/lib.rs#L457

lib/c-api/src/wasm_c_api/engine/config/jsc.rs

syrusakbary · 2025-02-28T14:32:17Z

lib/c-api/src/wasm_c_api/engine/config/mod.rs

+#[cfg(feature = "sys")]
+pub mod sys;
+#[cfg(feature = "sys")]
+pub use sys::wasm_config_set_sys_compiler;


I'd call this wasm_config_sys_set_compiler, so we can customize more settings in the future via wasm_config_sys_*

…epass` and `llvm` in `wasmer-api`

syrusakbary · 2025-02-28T16:15:46Z

lib/c-api/src/wasm_c_api/engine/config/wasmi.rs

+pub struct wasmer_wasmi_engine_config_t;
+
+/// Create a new  [`wasm_engine_t`] backed by a `wasmi` engine.
+pub fn wasm_wasmi_engine_new_with_config(config: wasm_config_t) -> Option<Box<wasm_engine_t>> {


This should not be public

syrusakbary · 2025-02-28T16:15:56Z

lib/c-api/src/wasm_c_api/engine/config/wamr.rs

+pub struct wasmer_wamr_engine_config_t;
+
+/// Create a new  [`wasm_engine_t`] backed by a `wamr` engine.
+pub fn wasm_wamr_engine_new_with_config(config: wasm_config_t) -> Option<Box<wasm_engine_t>> {


This should not be public

syrusakbary · 2025-02-28T16:16:01Z

lib/c-api/src/wasm_c_api/engine/config/v8.rs

+pub struct wasmer_v8_engine_config_t;
+
+/// Create a new  [`wasm_engine_t`] backed by a `v8` engine.
+pub fn wasm_v8_engine_new_with_config(config: wasm_config_t) -> Option<Box<wasm_engine_t>> {


This should not be public

syrusakbary · 2025-02-28T16:17:09Z

lib/c-api/src/wasm_c_api/engine/config/sys.rs

+}
+
+/// Create a new  [`wasm_engine_t`] backed by a `sys` engine.
+pub fn wasm_sys_engine_new_with_config(config: wasm_config_t) -> Option<Box<wasm_engine_t>> {


This should not be public

syrusakbary · 2025-02-28T16:17:50Z

lib/c-api/src/wasm_c_api/engine/config/jsc.rs

+pub struct wasmer_jsc_engine_config_t;
+
+/// Create a new  [`wasm_engine_t`] backed by a `jsc` engine.
+pub fn wasm_jsc_engine_new_with_config(config: wasm_config_t) -> Option<Box<wasm_engine_t>> {


This should not be public

…ate)`

…use `is_engine_available` to match

…_engine_t`

…e::get_exports()` in c_api backends

xdoardo added 5 commits February 28, 2025 14:31

fix(api): Minor changes to doc comments

02939f4

fix(api): Use BackendKind::default() to drive the decision of the d…

fc7cb8e

…efault backend ... so that we don't have to build an engine to find out which engine is the default one per the enabled features.

fix(api): Make sys::default_engine() public

8a3c5d8

fix(c-api): Enable multiple backends to be used with in wasmer's c-api

22707ea

chore: Remove forgotten debug statements

a7aaa72

xdoardo requested a review from syrusakbary as a code owner February 28, 2025 13:54

promptless bot mentioned this pull request Feb 28, 2025

docs: Add multiple backend support to C API docs wasmerio/docs.wasmer.io#118

Open

chore: Make linter happy

6c14f79

syrusakbary reviewed Feb 28, 2025

View reviewed changes

lib/c-api/src/wasm_c_api/engine/config/jsc.rs Outdated Show resolved Hide resolved

syrusakbary reviewed Feb 28, 2025

View reviewed changes

xdoardo added 5 commits February 28, 2025 15:53

fix(c-api): Fix message

422b00f

fix(c-api): rename wasm_config_x_sys to wasm_config_sys_x

0f304c4

fix(c-api): Fix pub re-export of sys::* items

460ca2a

fix(c-api): Fix feature gates

1617950

fix(c-api): Enable matching compiler features for cranelift, `singl…

1e6a748

…epass` and `llvm` in `wasmer-api`

syrusakbary reviewed Feb 28, 2025

View reviewed changes

xdoardo added 5 commits February 28, 2025 17:53

fix(c-api): Make <backend>_engine_new_with_config functions `pub(cr…

5c08932

…ate)`

fix(c-api): Make all the engines in the top-level enum visible, then …

4676bff

…use `is_engine_available` to match

fix(c-api): Re-instate wrongly deleted Default annotation for `wasm…

79b7708

…_engine_t`

fix(api): Use module.exports() to drive the order of `InstanceHandl…

fe348fa

…e::get_exports()` in c_api backends

fix(api): Make dep wat entail wasmparser

57cdaef

syrusakbary approved these changes Mar 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enable multiple backends supported by the api crate to be used in the c-api as well #5443

Enable multiple backends supported by the api crate to be used in the c-api as well #5443

xdoardo commented Feb 28, 2025 •

edited

Loading

promptless bot commented Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

syrusakbary Feb 28, 2025

xdoardo Feb 28, 2025

Enable multiple backends supported by the api crate to be used in the c-api as well #5443

Are you sure you want to change the base?

Enable multiple backends supported by the api crate to be used in the c-api as well #5443

Conversation

xdoardo commented Feb 28, 2025 • edited Loading

promptless bot commented Feb 28, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xdoardo commented Feb 28, 2025 •

edited

Loading