Merge pull request #399 from bytecodealliance/components-func

jbourassa · web-flow · commit bf01c0385aee · 2024-11-21T11:09:51.000-05:00
Replace `Instance#invoke` with `Func#call`
diff --git a/bench/component_id.rb b/bench/component_id.rb
@@ -6,14 +6,16 @@
   component = Wasmtime::Component::Component.from_file(engine, "spec/fixtures/component_types.wasm")
   store = Wasmtime::Store.new(engine)
   instance = linker.instantiate(store, component)
+  id_record = instance.get_func("id-record")
+  id_u32 = instance.get_func("id-u32")
 
   point_record = {"x" => 1, "y" => 2}
 
   x.report("identity point record") do
-    instance.invoke("id-record", point_record)
+    id_record.call(point_record)
   end
 
   x.report("identity u32") do
-    instance.invoke("id-u32", 10)
+    id_u32.call(10)
   end
 end
diff --git a/ext/src/ruby_api/component.rs b/ext/src/ruby_api/component.rs
@@ -161,6 +161,7 @@ pub fn init(ruby: &Ruby) -> Result<(), Error> {
 
     linker::init(ruby, &namespace)?;
     instance::init(ruby, &namespace)?;
+    func::init(ruby, &namespace)?;
     convert::init(ruby)?;
 
     Ok(())
diff --git a/ext/src/ruby_api/component/func.rs b/ext/src/ruby_api/component/func.rs
@@ -1,35 +1,118 @@
-use super::convert::{component_val_to_rb, rb_to_component_val};
-use crate::ruby_api::{errors::ExceptionMessage, store::StoreContextValue};
-use magnus::{exception::arg_error, prelude::*, value, Error, IntoValue, RArray, Value};
+use crate::ruby_api::{
+    component::{
+        convert::{component_val_to_rb, rb_to_component_val},
+        Instance,
+    },
+    errors::ExceptionMessage,
+    store::{Store, StoreContextValue},
+};
+use magnus::{
+    class, exception::arg_error, gc::Marker, method, prelude::*, typed_data::Obj, value,
+    DataTypeFunctions, Error, IntoValue, RArray, RModule, Ruby, TypedData, Value,
+};
 use wasmtime::component::{Func as FuncImpl, Type, Val};
 
-pub struct Func;
+/// @yard
+/// @rename Wasmtime::Component::Func
+/// Represents a WebAssembly component Function
+/// @see https://docs.wasmtime.dev/api/wasmtime/component/struct.Func.html Wasmtime's Rust doc
+///
+/// == Component model types conversion
+///
+/// Here's how component model types map to Ruby objects:
+///
+/// bool::
+///     Ruby +true+ or +false+, no automatic conversion happens.
+/// s8, u8, s16, u16, etc.::
+///     Ruby +Integer+. Overflows raise.
+/// f32, f64::
+///     Ruby +Float+.
+/// string::
+///     Ruby +String+. Exception will be raised if the string is not valid UTF-8.
+/// list<T>::
+///     Ruby +Array+.
+/// tuple::
+///     Ruby +Array+ of the same size of tuple. Example: +tuple<T, U>+ would be converted to +[T, U]+.
+/// record::
+///     Ruby +Hash+ where field names are +String+s.
+/// result<O, E>::
+///     {Result} instance. When converting a result branch of the none
+///     type, the {Result}’s value MUST be +nil+.
+///
+///     Examples of none type in a result: unparametrized +result+, +result<O>+, +result<_, E>+.
+/// option<T>::
+///     +nil+ is mapped to +None+, anything else is mapped to +Some(T)+.
+/// flags::
+///     Ruby +Array+ of +String+s.
+/// enum::
+///     Ruby +String+. Exception will be raised of the +String+ is not a valid enum value.
+/// variant::
+///     {Variant} instance wrapping the variant's name and optionally its value.
+///     Exception will be raised for:
+///     - invalid {Variant#name},
+///     - unparametrized variant and not nil {Variant#value}.
+/// resource (own<T> or borrow<T>)::
+///     Not yet supported.
+#[derive(TypedData)]
+#[magnus(class = "Wasmtime::Component::Func", size, mark, free_immediately)]
+pub struct Func {
+    store: Obj<Store>,
+    instance: Obj<Instance>,
+    inner: FuncImpl,
+}
+unsafe impl Send for Func {}
+
+impl DataTypeFunctions for Func {
+    fn mark(&self, marker: &Marker) {
+        marker.mark(self.store);
+        marker.mark(self.instance);
+    }
+}
 
 impl Func {
-    pub fn invoke(
-        store: &StoreContextValue,
-        func: &FuncImpl,
-        args: &[Value],
-    ) -> Result<Value, Error> {
-        let results_ty = func.results(store.context()?);
+    /// @yard
+    /// Calls a Wasm component model function.
+    /// @def call(*args)
+    /// @param args [Array<Object>] the function's arguments as per its Wasm definition
+    /// @return [Object] the function's return value as per its Wasm definition
+    /// @see Func Func class-level documentation for type conversion logic
+    pub fn call(&self, args: &[Value]) -> Result<Value, Error> {
+        Func::invoke(self.store, &self.inner, args)
+    }
+
+    pub fn from_inner(inner: FuncImpl, instance: Obj<Instance>, store: Obj<Store>) -> Self {
+        Self {
+            store,
+            instance,
+            inner,
+        }
+    }
+
+    pub fn invoke(store: Obj<Store>, func: &FuncImpl, args: &[Value]) -> Result<Value, Error> {
+        let store_context_value = StoreContextValue::from(store);
+        let results_ty = func.results(store.context_mut());
         let mut results = vec![wasmtime::component::Val::Bool(false); results_ty.len()];
-        let params = convert_params(store, &func.params(store.context()?), args)?;
+        let params = convert_params(
+            &store_context_value,
+            &func.params(store.context_mut()),
+            args,
+        )?;
 
-        func.call(store.context_mut()?, &params, &mut results)
-            .map_err(|e| store.handle_wasm_error(e))?;
+        func.call(store.context_mut(), &params, &mut results)
+            .map_err(|e| store_context_value.handle_wasm_error(e))?;
 
         let result = match results_ty.len() {
             0 => Ok(value::qnil().as_value()),
-            1 => component_val_to_rb(results.into_iter().next().unwrap(), store),
+            1 => component_val_to_rb(results.into_iter().next().unwrap(), &store_context_value),
             _ => results
                 .into_iter()
-                .map(|val| component_val_to_rb(val, store))
+                .map(|val| component_val_to_rb(val, &store_context_value))
                 .collect::<Result<RArray, Error>>()
                 .map(IntoValue::into_value),
         };
 
-        func.post_return(store.context_mut()?)
-            .map_err(|e| store.handle_wasm_error(e))?;
+        func.post_return(store.context_mut())
+            .map_err(|e| store_context_value.handle_wasm_error(e))?;
 
         result
     }
@@ -65,3 +148,10 @@ fn convert_params(
 
     Ok(params)
 }
+
+pub fn init(_ruby: &Ruby, namespace: &RModule) -> Result<(), Error> {
+    let func = namespace.define_class("Func", class::object())?;
+    func.define_method("call", method!(Func::call, -1))?;
+
+    Ok(())
+}
diff --git a/ext/src/ruby_api/component/instance.rs b/ext/src/ruby_api/component/instance.rs
@@ -5,7 +5,7 @@ use crate::error;
 use magnus::{
     class,
     error::ErrorType,
-    exception::arg_error,
+    exception::{arg_error, type_error},
     function,
     gc::Marker,
     method,
@@ -17,7 +17,7 @@ use magnus::{
     DataTypeFunctions, Error, RArray, Ruby, TryConvert, TypedData, Value,
 };
 use magnus::{IntoValue, RModule};
-use wasmtime::component::{Instance as InstanceImpl, Type, Val};
+use wasmtime::component::{ComponentExportIndex, Instance as InstanceImpl, Type, Val};
 
 /// @yard
 /// Represents a WebAssembly component instance.
@@ -43,33 +43,63 @@ impl Instance {
     }
 
     /// @yard
-    /// Retrieves a Wasm function from the component instance and calls it.
+    /// Retrieves a Wasm function from the component instance.
     ///
-    /// @def invoke(name, *args)
-    /// @param name [String] The name of function  to run.
-    /// @param (see Component::Func#call)
-    /// @return (see Component::Func#call)
-    /// @see Component::Func#call
-    pub fn invoke(&self, args: &[Value]) -> Result<Value, Error> {
-        let name = RString::try_convert(*args.first().ok_or_else(|| {
+    /// @def get_func(handle)
+    /// @param handle [String, Array<String>] The path of the function to retrieve
+    /// @return [Func, nil] The function if it exists, nil otherwise
+    ///
+    /// @example Retrieve a top-level +add+ export:
+    ///   instance.get_func("add")
+    ///
+    /// @example Retrieve an +add+ export nested under an +adder+ instance top-level export:
+    ///   instance.get_func(["adder", "add"])
+    pub fn get_func(rb_self: Obj<Self>, handle: Value) -> Result<Option<Func>, Error> {
+        let func = rb_self
+            .export_index(handle)?
+            .and_then(|index| rb_self.inner.get_func(rb_self.store.context_mut(), index))
+            .map(|inner| Func::from_inner(inner, rb_self, rb_self.store));
+
+        Ok(func)
+    }
+
+    fn export_index(&self, handle: Value) -> Result<Option<ComponentExportIndex>, Error> {
+        let invalid_arg = || {
             Error::new(
-                magnus::exception::type_error(),
-                "wrong number of arguments (given 0, expected 1+)",
+                type_error(),
+                format!(
+                    "invalid argument for component index, expected String | Array<String>, got {}",
+                    handle.inspect()
+                ),
             )
-        })?)?;
+        };
+
+        let index = if let Some(name) = RString::from_value(handle) {
+            self.inner
+                .get_export(self.store.context_mut(), None, unsafe { name.as_str()? })
+        } else if let Some(names) = RArray::from_value(handle) {
+            unsafe { names.as_slice() }
+                .iter()
+                .try_fold::<_, _, Result<_, Error>>(None, |index, name| {
+                    let name = RString::from_value(*name).ok_or_else(invalid_arg)?;
 
-        let func = self
-            .inner
-            .get_func(self.store.context_mut(), unsafe { name.as_str()? })
-            .ok_or_else(|| error!("function \"{}\" not found", name))?;
+                    Ok(self
+                        .inner
+                        .get_export(self.store.context_mut(), index.as_ref(), unsafe {
+                            name.as_str()?
+                        }))
+                })?
+        } else {
+            return Err(invalid_arg());
+        };
 
-        Func::invoke(&self.store.into(), &func, &args[1..])
+        Ok(index)
     }
 }
 
 pub fn init(_ruby: &Ruby, namespace: &RModule) -> Result<(), Error> {
     let instance = namespace.define_class("Instance", class::object())?;
-    instance.define_method("invoke", method!(Instance::invoke, -1))?;
+    instance.define_method("get_func", method!(Instance::get_func, 1))?;
 
     Ok(())
 }
diff --git a/spec/fixtures/component_adder.wat b/spec/fixtures/component_adder.wat
@@ -1,12 +1,22 @@
 (component
-  (core module $m
-    (func (export "add") (param $a i32) (param $b i32) (result i32)
-      local.get $a
-      local.get $b
-      i32.add
+  ;; Define a nested component so we can export an instance of a component
+  (component $c
+    (core module $m
+        (func (export "add") (param $a i32) (param $b i32) (result i32)
+        local.get $a
+        local.get $b
+        i32.add
+        )
     )
+    (core instance $i (instantiate $m))
+    (func $add (param "a" s32) (param "b" s32) (result s32) (canon lift (core func $i "add")))
+    (export "add" (func $add))
   )
-  (core instance $i (instantiate $m))
-  (func $add (param "a" s32) (param "b" s32) (result s32) (canon lift (core func $i "add")))
-  (export "add" (func $add))
+  (instance $adder (instantiate $c))
+
+  ;; Export the adder instance
+  (export "adder" (instance $adder))
+
+  ;; Re-export add as a top level
+  (export "add" (func $adder "add"))
 )
diff --git a/spec/unit/component/convert_spec.rb b/spec/unit/component/convert_spec.rb
@@ -10,6 +10,13 @@ module Component
       let(:linker) { Linker.new(GLOBAL_ENGINE) }
       let(:instance) { linker.instantiate(Store.new(GLOBAL_ENGINE), @types_component) }
 
+      def call_func(name, *args)
+        func = instance.get_func(name)
+        raise "Unknown func: #{name}" if func.nil?
+
+        func.call(*args)
+      end
+
       describe "successful round-trips" do
         [
           ["bool", true, false],
@@ -37,17 +44,17 @@ module Component
         ].each do |type, *values|
           values.each do |v|
             it "#{type} #{v.inspect}" do
-              expect(instance.invoke("id-#{type}", v)).to eq(v)
+              expect(call_func("id-#{type}", v)).to eq(v)
             end
           end
         end
 
         it "returns FLOAT::INFINITY on f32 overflow" do
-          expect(instance.invoke("id-f32", 5 * 10**40)).to eq(Float::INFINITY)
+          expect(call_func("id-f32", 5 * 10**40)).to eq(Float::INFINITY)
         end
 
         it "returns FLOAT::INFINITY on f64 overflow" do
-          expect(instance.invoke("id-f64", 2 * 10**310)).to eq(Float::INFINITY)
+          expect(call_func("id-f64", 2 * 10**310)).to eq(Float::INFINITY)
         end
       end
 
@@ -95,22 +102,22 @@ module Component
           ["flags", 1, /no implicit conversion of Integer into Array/]
         ].each do |type, value, klass, msg|
           it "fails on #{type} #{value.inspect}" do
-            expect { instance.invoke("id-#{type}", value) }.to raise_error(klass, msg)
+            expect { call_func("id-#{type}", value) }.to raise_error(klass, msg)
           end
         end
 
         it "has item index in list conversion error" do
-          expect { instance.invoke("id-list", [1, "foo"]) }
+          expect { call_func("id-list", [1, "foo"]) }
             .to raise_error(TypeError, /list item at index 1/)
         end
 
         it "has tuple index in tuple conversion error" do
-          expect { instance.invoke("id-tuple", ["foo", 1]) }
+          expect { call_func("id-tuple", ["foo", 1]) }
             .to raise_error(TypeError, /tuple value at index 0/)
         end
 
         it "has field name in record conversion error" do
-          expect { instance.invoke("id-record", {"y" => 1, "x" => nil}) }
+          expect { call_func("id-record", {"y" => 1, "x" => nil}) }
             .to raise_error(TypeError, /struct field "x"/)
         end
       end
diff --git a/spec/unit/component/func_spec.rb b/spec/unit/component/func_spec.rb
diff --git a/spec/unit/component/instance_spec.rb b/spec/unit/component/instance_spec.rb
