Skip to main content

tvm_ffi/
function.rs

1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements.  See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership.  The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License.  You may obtain a copy of the License at
9 *
10 *   http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied.  See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19//! [`Function`], a callable shared with C++ and Python, and the global function
20//! registry.
21
22pub use crate::function_internal::{AsPackedCallable, PackedCallArg, PackedCallArgs};
23
24use crate::any::{Any, AnyView};
25use crate::derive::{Object, ObjectRef};
26use crate::error::{Error, Result};
27use crate::object::{Object, ObjectArc, ObjectCore};
28use crate::type_traits::AnyCompatible;
29use tvm_ffi_sys::{
30    TVMFFIAny, TVMFFIByteArray, TVMFFIFunctionCell, TVMFFIFunctionCreate, TVMFFIFunctionGetGlobal,
31    TVMFFIFunctionSetGlobalFromMethodInfo, TVMFFIMethodInfo, TVMFFIObjectHandle,
32    TVMFFISafeCallType, TVMFFITypeIndex,
33};
34
35/// The object behind a [`Function`].
36#[repr(C)]
37#[derive(Object)]
38#[object(type_key = "ffi.Function", unsafe type_index = TVMFFITypeIndex::kTVMFFIFunction)]
39pub struct FunctionObj {
40    object: Object,
41    cell: TVMFFIFunctionCell,
42}
43
44/// A type-erased callable that works across languages.
45///
46/// A `Function` takes [`AnyView`] arguments and returns an [`Any`]. Make one
47/// from a Rust closure with [`from_typed`](Self::from_typed), look one up by
48/// name with [`get_global`](Self::get_global), and call it with
49/// [`call_tuple`](Self::call_tuple) or [`call_packed`](Self::call_packed).
50/// [`into_typed_fn!`](crate::into_typed_fn) turns it back into a typed closure.
51///
52/// # Examples
53///
54/// ```
55/// use tvm_ffi::{Function, Result};
56///
57/// let add = Function::from_typed(|x: i64, y: i64| -> Result<i64> { Ok(x + y) });
58/// let sum = i64::try_from(add.call_tuple((1_i64, 2_i64))?)?;
59/// assert_eq!(sum, 3);
60/// # Ok::<(), tvm_ffi::Error>(())
61/// ```
62///
63/// A `Function` may be called from any thread, so a Rust callback must be
64/// `Send + Sync`; a callback holding an `Rc` is rejected. A function written
65/// in another language is as thread-safe as its implementation.
66///
67/// ```compile_fail,E0277
68/// use std::rc::Rc;
69/// let count = Rc::new(0_i64);
70/// tvm_ffi::Function::from_typed(move || -> tvm_ffi::Result<i64> { Ok(*count) });
71/// ```
72#[derive(Clone, ObjectRef)]
73#[object_ref(skip_deref)]
74pub struct Function {
75    data: ObjectArc<FunctionObj>,
76}
77
78// SAFETY: a `Function` is immutable, every Rust callback it wraps is `Send + Sync`,
79// and `from_extern_c` requires the same of foreign callbacks.
80unsafe impl Send for Function {}
81unsafe impl Sync for Function {}
82
83//------------------------------------------------------------------------
84// CallbackFunctionObjImpl
85//------------------------------------------------------------------------
86/// Special helper class to hold a generic callback state as Object
87/// Logically this Impl can be viewed as a FunctionObj
88/// We can create an ObjectArc<CallbackFunctionObjImpl<F>> so the deleter
89/// can correctly delete the entire object including callback part
90/// then we will convert to ObjectArc<FunctionObj> to be used as function
91#[repr(C)]
92struct CallbackFunctionObjImpl<F: Fn(&[AnyView]) -> Result<Any> + Send + Sync + 'static> {
93    function: FunctionObj,
94    callback: F,
95}
96
97impl<F: Fn(&[AnyView]) -> Result<Any> + Send + Sync + 'static> CallbackFunctionObjImpl<F> {
98    pub fn from_callback(callback: F) -> Self {
99        Self {
100            function: FunctionObj {
101                object: Object::new(),
102                cell: TVMFFIFunctionCell {
103                    // specfic callback for F
104                    safe_call: Self::invoke_callback,
105                    cxx_call: std::ptr::null_mut(),
106                },
107            },
108            callback,
109        }
110    }
111
112    unsafe extern "C" fn invoke_callback(
113        handle: *mut std::ffi::c_void,
114        args: *const TVMFFIAny,
115        num_args: i32,
116        result: *mut TVMFFIAny,
117    ) -> i32 {
118        let this = unsafe { &*(handle as *mut Self) };
119        let packed_args = unsafe { crate::function_internal::packed_args(args, num_args) };
120        let ret_value = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
121            (this.callback)(packed_args)
122        })) {
123            Ok(ret_value) => ret_value,
124            Err(payload) => Err(Error::from_panic(payload)),
125        };
126        match ret_value {
127            Ok(value) => {
128                unsafe { *result = Any::into_raw_ffi_any(value) };
129                0
130            }
131            Err(error) => {
132                Error::set_raised(&error);
133                -1
134            }
135        }
136    }
137}
138
139unsafe impl<F: Fn(&[AnyView]) -> Result<Any> + Send + Sync + 'static> ObjectCore
140    for CallbackFunctionObjImpl<F>
141{
142    type Parent = FunctionObj;
143    const TYPE_KEY: &'static str = FunctionObj::TYPE_KEY;
144    const TYPE_DEPTH: i32 = FunctionObj::TYPE_DEPTH;
145    fn type_index() -> i32 {
146        FunctionObj::type_index()
147    }
148    unsafe fn object_header_mut(this: &mut Self) -> &mut tvm_ffi_sys::TVMFFIObject {
149        unsafe { FunctionObj::object_header_mut(&mut this.function) }
150    }
151}
152
153impl Function {
154    /// Call the function with the arguments `packed_args`.
155    ///
156    /// # Arguments
157    ///
158    /// * `packed_args` - The arguments, one [`AnyView`] each.
159    ///
160    /// # Returns
161    ///
162    /// The function's result.
163    ///
164    /// # Errors
165    ///
166    /// Returns the error that the function raises.
167    ///
168    /// ```
169    /// use tvm_ffi::{AnyView, Function, Result};
170    /// let add = Function::from_typed(|x: i64, y: i64| -> Result<i64> { Ok(x + y) });
171    /// let result = add.call_packed(&[AnyView::from(&1_i64), AnyView::from(&2_i64)])?;
172    /// assert_eq!(i64::try_from(result)?, 3);
173    /// # Ok::<(), tvm_ffi::Error>(())
174    /// ```
175    ///
176    /// See also [`Function`].
177    pub fn call_packed(&self, packed_args: &[AnyView]) -> Result<Any> {
178        unsafe {
179            let packed_args_ptr = packed_args.as_ptr() as *const TVMFFIAny;
180            let mut result = Any::new();
181            let ret_code = (self.data.cell.safe_call)(
182                ObjectArc::as_ptr(&self.data) as *mut FunctionObj as *mut std::ffi::c_void,
183                packed_args_ptr,
184                packed_args.len() as i32,
185                Any::as_raw_ffi_any_mut(&mut result),
186            );
187            if ret_code == 0 {
188                Ok(result)
189            } else {
190                Err(Error::from_raised())
191            }
192        }
193    }
194
195    /// Call the function with the arguments in the tuple `tuple_args`.
196    ///
197    /// An element may be a value or a reference to one; a reference passes an
198    /// object without retaining it, and a `&str` or `&[u8]` passes as a
199    /// `String` or `Bytes`.
200    ///
201    /// # Arguments
202    ///
203    /// * `tuple_args` - The arguments, as a tuple such as `(1_i64, &array)`.
204    ///
205    /// # Returns
206    ///
207    /// The function's result.
208    ///
209    /// # Errors
210    ///
211    /// Returns the error that the function raises.
212    ///
213    /// See also [`Function`].
214    pub fn call_tuple(&self, tuple_args: impl PackedCallArgs) -> Result<Any> {
215        tuple_args.with_packed_args(|packed_args| self.call_packed(packed_args))
216    }
217    /// Look up the global function registered as `name`.
218    ///
219    /// # Arguments
220    ///
221    /// * `name` - The name of the function, such as `"my_ext.double"`.
222    ///
223    /// # Returns
224    ///
225    /// The global function.
226    ///
227    /// # Errors
228    ///
229    /// Returns a `ValueError` if no function is registered as `name`, as C++
230    /// `Function::GetGlobalRequired`. Probe with `.ok()` where a missing
231    /// function is expected.
232    ///
233    /// ```standalone_crate
234    /// use tvm_ffi::Function;
235    /// let double = Function::from_typed(|x: i64| -> tvm_ffi::Result<i64> { Ok(x * 2) });
236    /// Function::register_global("my_ext.double", double)?;
237    /// let double = Function::get_global("my_ext.double")?;
238    /// assert_eq!(i64::try_from(double.call_tuple((21_i64,))?)?, 42);
239    /// # Ok::<(), tvm_ffi::Error>(())
240    /// ```
241    ///
242    /// See also [`register_global_typed`](Self::register_global_typed).
243    pub fn get_global(name: &str) -> Result<Function> {
244        unsafe {
245            let name_arg = TVMFFIByteArray::from_str(name);
246            let mut result: TVMFFIObjectHandle = ::std::ptr::null_mut();
247            crate::check_safe_call!(TVMFFIFunctionGetGlobal(&name_arg, &mut result))?;
248            if result.is_null() {
249                crate::bail!(crate::error::VALUE_ERROR, "Function {} not found", name);
250            }
251            Ok(Self {
252                data: ObjectArc::<FunctionObj>::from_raw(result as *mut FunctionObj),
253            })
254        }
255    }
256
257    /// Register a function as a global function, which every language can then
258    /// look up by name.
259    ///
260    /// The function's metadata records only that it is a function, with no
261    /// parameter types. Use [`Function::register_global_typed`] to record the
262    /// parameter and return types of a typed function, and a doc string.
263    ///
264    /// # Arguments
265    ///
266    /// * `name` - The name of the function.
267    /// * `func` - The function to register.
268    ///
269    /// # Returns
270    ///
271    /// `Ok(())` once the function is registered.
272    ///
273    /// # Errors
274    ///
275    /// Returns an error if the registration fails.
276    ///
277    /// See also [`get_global`](Self::get_global).
278    pub fn register_global(name: &str, func: Function) -> Result<()> {
279        let type_schema = crate::type_traits::type_schema(FunctionObj::TYPE_KEY, &[]);
280        Self::register_global_with_info(name, &func, &type_schema, "")
281    }
282
283    /// Register a typed function as a global function, with a doc string.
284    ///
285    /// The function's metadata records its type schema, the parameter and
286    /// return types, which `tvm_ffi.get_global_func_metadata` and the stub
287    /// generator read. An empty `doc` records no doc string.
288    ///
289    /// # Arguments
290    ///
291    /// * `name` - The name of the function.
292    /// * `func` - The typed function to register, as for [`Function::from_typed`].
293    /// * `doc` - The doc string of the function.
294    ///
295    /// # Returns
296    ///
297    /// `Ok(())` once the function is registered.
298    ///
299    /// # Errors
300    ///
301    /// Returns an error if the registration fails.
302    ///
303    /// ```standalone_crate
304    /// use tvm_ffi::{Function, Result};
305    /// let add = |x: i64, y: i64| -> Result<i64> { Ok(x + y) };
306    /// Function::register_global_typed("my_ext.add", add, "Add two integers.")?;
307    /// # Ok::<(), tvm_ffi::Error>(())
308    /// ```
309    ///
310    /// See also [`get_global`](Self::get_global).
311    pub fn register_global_typed<F, I, O>(name: &str, func: F, doc: &str) -> Result<()>
312    where
313        F: AsPackedCallable<I, O> + Send + Sync + 'static,
314    {
315        let type_schema = F::type_schema();
316        Self::register_global_with_info(name, &Self::from_typed(func), &type_schema, doc)
317    }
318
319    fn register_global_with_info(
320        name: &str,
321        func: &Function,
322        type_schema: &str,
323        doc: &str,
324    ) -> Result<()> {
325        let metadata = crate::type_traits::type_schema_metadata(type_schema);
326        let mut method = TVMFFIAny::new();
327        unsafe {
328            <Function as AnyCompatible>::copy_to_any_view(func, &mut method);
329            let info = TVMFFIMethodInfo {
330                name: TVMFFIByteArray::from_str(name),
331                doc: TVMFFIByteArray::from_str(doc),
332                metadata: TVMFFIByteArray::from_str(&metadata),
333                flags: 0,
334                method,
335            };
336            let can_override = 0;
337            crate::check_safe_call!(TVMFFIFunctionSetGlobalFromMethodInfo(&info, can_override))
338        }
339    }
340    /// Construct a function from a packed function, which takes its arguments as a
341    /// slice.
342    ///
343    /// Use it for a variable number of arguments; otherwise
344    /// [`from_typed`](Self::from_typed) converts the arguments for you. Report
345    /// errors by returning them. A panic in `func` is caught and raised to the
346    /// caller as an `InternalError`, but panicking is discouraged.
347    ///
348    /// # Arguments
349    ///
350    /// * `func` - The packed function, of signature `Fn(&[AnyView]) -> Result<Any>`.
351    ///
352    /// # Returns
353    ///
354    /// The function.
355    ///
356    /// ```
357    /// use tvm_ffi::{Any, AnyView, Function, Result};
358    /// let count = Function::from_packed(|args: &[AnyView]| -> Result<Any> {
359    ///     Ok(Any::from(args.len() as i64))
360    /// });
361    /// assert_eq!(i64::try_from(count.call_tuple((1_i64, true))?)?, 2);
362    /// # Ok::<(), tvm_ffi::Error>(())
363    /// ```
364    ///
365    /// See also [`Function`].
366    pub fn from_packed<F>(func: F) -> Self
367    where
368        F: Fn(&[AnyView]) -> Result<Any> + Send + Sync + 'static,
369    {
370        unsafe {
371            let callback_arc = ObjectArc::new(CallbackFunctionObjImpl::from_callback(func));
372            let func_arc = ObjectArc::<FunctionObj>::from_raw(
373                ObjectArc::into_raw(callback_arc) as *mut FunctionObj
374            );
375            Self { data: func_arc }
376        }
377    }
378
379    /// Construct a function from a typed function.
380    ///
381    /// Each argument is converted to its parameter type, and a mismatch raises a
382    /// `TypeError` to the caller. Report errors by returning them. A panic in
383    /// `func` is caught and raised to the caller as an `InternalError`, but
384    /// panicking is discouraged.
385    ///
386    /// # Arguments
387    ///
388    /// * `func` - The typed function, an [`AsPackedCallable`] such as
389    ///   `Fn(T0, T1, ...) -> Result<O>`; each parameter is an `AnyCompatible`
390    ///   type, a `TensorView` or an `RValueRef<T>`.
391    ///
392    /// # Returns
393    ///
394    /// The function.
395    ///
396    /// ```
397    /// use tvm_ffi::{Function, Result};
398    /// let scale = Function::from_typed(|x: f64, factor: f64| -> Result<f64> { Ok(x * factor) });
399    /// assert_eq!(f64::try_from(scale.call_tuple((2.0_f64, 1.5_f64))?)?, 3.0);
400    /// # Ok::<(), tvm_ffi::Error>(())
401    /// ```
402    ///
403    /// See also [`Function`].
404    pub fn from_typed<F, I, O>(func: F) -> Self
405    where
406        F: AsPackedCallable<I, O> + Send + Sync + 'static,
407    {
408        let closure = move |packed_args: &[AnyView]| -> Result<Any> {
409            let ret_value = func.call_packed(packed_args)?;
410            Ok(ret_value)
411        };
412        Self::from_packed(closure)
413    }
414
415    /// Wrap a C callback as a Function.
416    ///
417    /// # Safety
418    ///
419    /// `handle` (may be null) is the state `safe_call` receives; `deleter` frees it
420    /// when the Function drops. All three must be safe to use from any thread.
421    ///
422    /// # Errors
423    ///
424    /// Returns an error if the runtime cannot allocate the function. The
425    /// function then does not take `handle`: `deleter` is not called, and the
426    /// caller still owns `handle`.
427    pub unsafe fn from_extern_c(
428        handle: *mut std::ffi::c_void,
429        safe_call: TVMFFISafeCallType,
430        deleter: Option<unsafe extern "C" fn(*mut std::ffi::c_void)>,
431    ) -> Result<Self> {
432        unsafe {
433            let mut out_handle: TVMFFIObjectHandle = std::ptr::null_mut();
434            crate::check_safe_call!(TVMFFIFunctionCreate(
435                handle,
436                safe_call,
437                deleter,
438                &mut out_handle
439            ))?;
440            Ok(Self {
441                data: ObjectArc::<FunctionObj>::from_raw(out_handle as *mut FunctionObj),
442            })
443        }
444    }
445}