Merge #1924 #1934

1924: Export wasmer::{BaseTunables, Tunables} r=Hywan a=webmaster128

Closes #1872

ping @Hywan 

# Review

- [x] Add a short description of the the change to the CHANGELOG.md file


1934: Point to `native` versions of functions in Function docs r=Hywan a=MarkMcCaskey

It's not obvious from looking at the docs for `Function` that there are native variants.  This PR makes it clear that when users are figuring out how to make functions that they're shown the `native` variants.

Co-authored-by: Simon Warta <simon@warta.it>
Co-authored-by: Mark McCaskey <mark@wasmer.io>

CHANGELOG.md

@@ -21,6 +21,7 @@
 - [#1851](https://github.com/wasmerio/wasmer/pull/1851) Improve test suite and documentation of the Wasmer C API
 - [#1874](https://github.com/wasmerio/wasmer/pull/1874) Set `CompilerConfig` to be owned (following wasm-c-api)
 - [#1880](https://github.com/wasmerio/wasmer/pull/1880) Remove cmake dependency for tests
+- [#1924](https://github.com/wasmerio/wasmer/pull/1924) Rename reference implementation `wasmer::Tunables` to `wasmer::BaseTunables`. Export trait `wasmer_engine::Tunables` as `wasmer::Tunables`.
 
 ### Fixed
 

examples/tunables_limit_memory.rs

@@ -4,11 +4,10 @@ use std::sync::Arc;
 use wasmer::{
     imports,
     vm::{self, MemoryError, MemoryStyle, TableStyle, VMMemoryDefinition, VMTableDefinition},
-    wat2wasm, Instance, Memory, MemoryType, Module, Pages, Store, TableType, Target,
-    Tunables as ReferenceTunables,
+    wat2wasm, BaseTunables, Instance, Memory, MemoryType, Module, Pages, Store, TableType, Target,
+    Tunables,
 };
 use wasmer_compiler_cranelift::Cranelift;
-use wasmer_engine::Tunables;
 use wasmer_engine_jit::JIT;
 
 /// A custom tunables that allows you to set a memory limit.
@@ -29,7 +28,7 @@ impl<T: Tunables> LimitingTunables<T> {
         Self { limit, base }
     }
 
-    /// Takes in input memory type as requested by the guest and sets
+    /// Takes an input memory type as requested by the guest and sets
     /// a maximum if missing. The resulting memory type is final if
     /// valid. However, this can produce invalid types, such that
     /// validate_memory must be called before creating the memory.
@@ -147,7 +146,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Here is where the fun begins
 
-    let base = ReferenceTunables::for_target(&Target::default());
+    let base = BaseTunables::for_target(&Target::default());
     let tunables = LimitingTunables::new(base, Pages(24));
 
     // Create a store, that holds the engine and our custom tunables

lib/api/src/externals/function.rs

@@ -69,6 +69,9 @@ pub struct Function {
 impl Function {
     /// Creates a new host `Function` (dynamic) with the provided signature.
     ///
+    /// If you know the signature of the host function at compile time,
+    /// consider using [`Function::new_native`] for less runtime overhead.
+    ///
     /// # Examples
     ///
     /// ```
@@ -134,6 +137,10 @@ impl Function {
 
     /// Creates a new host `Function` (dynamic) with the provided signature and environment.
     ///
+    /// If you know the signature of the host function at compile time,
+    /// consider using [`Function::new_native_with_env`] for less runtime
+    /// overhead.
+    ///
     /// # Examples
     ///
     /// ```

lib/api/src/lib.rs

@@ -294,7 +294,7 @@ pub use crate::module::Module;
 pub use crate::native::NativeFunc;
 pub use crate::ptr::{Array, Item, WasmPtr};
 pub use crate::store::{Store, StoreObject};
-pub use crate::tunables::Tunables;
+pub use crate::tunables::BaseTunables;
 pub use crate::types::{
     ExportType, ExternRef, ExternType, FunctionType, GlobalType, HostInfo, HostRef, ImportType,
     MemoryType, Mutability, TableType, Val, ValType,
@@ -311,7 +311,7 @@ pub use wasmer_compiler::{
 };
 pub use wasmer_engine::{
     ChainableNamedResolver, DeserializeError, Engine, Export, FrameInfo, LinkError, NamedResolver,
-    NamedResolverChain, Resolver, RuntimeError, SerializeError,
+    NamedResolverChain, Resolver, RuntimeError, SerializeError, Tunables,
 };
 pub use wasmer_types::{
     Atomically, Bytes, ExportIndex, GlobalInit, LocalFunctionIndex, MemoryView, Pages, ValueType,

lib/api/src/store.rs

@@ -1,10 +1,9 @@
-use crate::tunables::Tunables;
+use crate::tunables::BaseTunables;
 use std::fmt;
 use std::sync::Arc;
 #[cfg(all(feature = "compiler", feature = "engine"))]
 use wasmer_compiler::CompilerConfig;
-use wasmer_engine::Engine;
-use wasmer_engine::Tunables as BaseTunables;
+use wasmer_engine::{Engine, Tunables};
 
 /// The store represents all global state that can be manipulated by
 /// WebAssembly programs. It consists of the runtime representation
@@ -19,7 +18,7 @@ use wasmer_engine::Tunables as BaseTunables;
 #[derive(Clone)]
 pub struct Store {
     engine: Arc<dyn Engine + Send + Sync>,
-    tunables: Arc<dyn BaseTunables + Send + Sync>,
+    tunables: Arc<dyn Tunables + Send + Sync>,
 }
 
 impl Store {
@@ -30,15 +29,12 @@ impl Store {
     {
         Self {
             engine: engine.cloned(),
-            tunables: Arc::new(Tunables::for_target(engine.target())),
+            tunables: Arc::new(BaseTunables::for_target(engine.target())),
         }
     }
 
     /// Creates a new `Store` with a specific [`Engine`] and [`Tunables`].
-    pub fn new_with_tunables<E>(
-        engine: &E,
-        tunables: impl BaseTunables + Send + Sync + 'static,
-    ) -> Self
+    pub fn new_with_tunables<E>(engine: &E, tunables: impl Tunables + Send + Sync + 'static) -> Self
     where
         E: Engine + ?Sized,
     {
@@ -49,7 +45,7 @@ impl Store {
     }
 
     /// Returns the [`Tunables`].
-    pub fn tunables(&self) -> &dyn BaseTunables {
+    pub fn tunables(&self) -> &dyn Tunables {
         self.tunables.as_ref()
     }
 
@@ -111,7 +107,7 @@ impl Default for Store {
 
         let config = get_config();
         let engine = get_engine(config);
-        let tunables = Tunables::for_target(engine.target());
+        let tunables = BaseTunables::for_target(engine.target());
         Store {
             engine: Arc::new(engine),
             tunables: Arc::new(tunables),

lib/api/src/tunables.rs

@@ -4,16 +4,23 @@ use std::ptr::NonNull;
 use std::sync::Arc;
 use target_lexicon::{OperatingSystem, PointerWidth};
 use wasmer_compiler::Target;
-use wasmer_engine::Tunables as BaseTunables;
+use wasmer_engine::Tunables;
 use wasmer_vm::MemoryError;
 use wasmer_vm::{
     LinearMemory, LinearTable, Memory, MemoryStyle, Table, TableStyle, VMMemoryDefinition,
     VMTableDefinition,
 };
 
 /// Tunable parameters for WebAssembly compilation.
+/// This is the reference implementation of the `Tunables` trait,
+/// used by default.
+///
+/// You can use this as a template for creating a custom Tunables
+/// implementation or use composition to wrap your Tunables around
+/// this one. The later approach is demonstrated in the
+/// tunables-limit-memory example.
 #[derive(Clone)]
-pub struct Tunables {
+pub struct BaseTunables {
     /// For static heaps, the size in wasm pages of the heap protected by bounds checking.
     pub static_memory_bound: Pages,
 
@@ -24,8 +31,8 @@ pub struct Tunables {
     pub dynamic_memory_offset_guard_size: u64,
 }
 
-impl Tunables {
-    /// Get the `Tunables` for a specific Target
+impl BaseTunables {
+    /// Get the `BaseTunables` for a specific Target
     pub fn for_target(target: &Target) -> Self {
         let triple = target.triple();
         let pointer_width: PointerWidth = triple.pointer_width().unwrap();
@@ -61,7 +68,7 @@ impl Tunables {
     }
 }
 
-impl BaseTunables for Tunables {
+impl Tunables for BaseTunables {
     /// Get a `MemoryStyle` for the provided `MemoryType`
     fn memory_style(&self, memory: &MemoryType) -> MemoryStyle {
         // A heap with a maximum that doesn't exceed the static memory bound specified by the
@@ -148,7 +155,7 @@ mod tests {
 
     #[test]
     fn memory_style() {
-        let tunables = Tunables {
+        let tunables = BaseTunables {
             static_memory_bound: Pages(2048),
             static_memory_offset_guard_size: 128,
             dynamic_memory_offset_guard_size: 256,