Skip to main content

tvm_ffi/reflection/
native_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//! Typed hooks that registries hold: native functions with a packed fallback.
20
21use std::ffi::c_void;
22use std::marker::PhantomData;
23
24use crate::object::type_key_of_index;
25use crate::tvm_ffi_sys::{TVMFFIAny, TVMFFITypeIndex};
26use crate::type_traits::DowncastRefFromObject;
27use crate::{Any, AnyView, Error, Function, Result, TYPE_ERROR};
28
29/// A typed hook that a type attribute, an enum attribute or another registry
30/// slot holds: a native function, called directly through the C ABI, or a
31/// packed [`Function`] registered in its place.
32///
33/// `Args` is the tuple of argument types and `R` the result type, as in
34/// `Fn(Args) -> R`: a hook that checks a pair is a
35/// `NativeFunction<(&MyPairObj,)>`, and one that measures it a
36/// `NativeFunction<(&MyPairObj,), i64>`. An argument is a borrowed object
37/// (`&MyPairObj`), a borrowed managed reference (`&Array<T>`) or `&Any`, and a
38/// native function receives its address, which C++ declares as
39/// `const MyPairObj*`, `const Array<T>&` or `const Any&`.
40///
41/// A native function carries no signature at run time, so the slot declares
42/// it. Reading a hook with [`from_any`](Self::from_any) is `unsafe`, the
43/// caller vouching for the signature, and then calling it is safe. Building a
44/// hook from a Rust function with `into()` is safe; storing it, with
45/// [`TypeAttrDef::set_native_fn_attr`](super::TypeAttrDef::set_native_fn_attr) or
46/// [`EnumDef::set_native_fn_attr`](super::EnumDef::set_native_fn_attr), or
47/// converting it to [`Any`] for another registry with
48/// [`into_any`](Self::into_any), is `unsafe`, the caller vouching that the
49/// slot's callers use exactly this signature.
50///
51/// # Examples
52///
53/// ```standalone_crate
54/// use tvm_ffi::reflection::{NativeFunction, TypeAttrColumn, TypeAttrDef};
55/// use tvm_ffi::{rs_object, Object, ObjectArc, ObjectCore, Result};
56///
57/// #[rs_object(type_key = "my_ext.MyPair")]
58/// pub struct MyPairObj {
59///     base_: Object,
60///     first: i64,
61///     second: i64,
62/// }
63///
64/// fn sum(pair: &MyPairObj) -> Result<i64> {
65///     Ok(pair.first + pair.second)
66/// }
67///
68/// let hook: NativeFunction<(&MyPairObj,), i64> = sum.into();
69/// // SAFETY: `my_ext.sum` holds `i64(const MyPairObj*)` hooks.
70/// unsafe { TypeAttrDef::<MyPairObj>::new().set_native_fn_attr("my_ext.sum", hook)? };
71///
72/// let stored = TypeAttrColumn::lookup("my_ext.sum").unwrap().get(MyPairObj::type_index()).unwrap();
73/// // SAFETY: `my_ext.sum` holds `i64(const MyPairObj*)` hooks.
74/// let sum: NativeFunction<(&MyPairObj,), i64> = unsafe { NativeFunction::from_any(stored)? };
75/// let pair = ObjectArc::new(MyPairObj { base_: Object::new(), first: 1, second: 2 });
76/// assert_eq!(sum.call((&*pair,))?, 3);
77/// # Ok::<(), tvm_ffi::Error>(())
78/// ```
79pub struct NativeFunction<Args, R = ()> {
80    // A non-null opaque pointer to the native function, or a `Function`.
81    data: Any,
82    // Covariant in `Args`: a hook that takes `&'a T` takes any shorter borrow.
83    signature: PhantomData<fn() -> (Args, R)>,
84}
85
86impl<Args: NativeArgs, R: TryFrom<Any>> NativeFunction<Args, R> {
87    /// Call the hook with `args`.
88    ///
89    /// # Arguments
90    ///
91    /// * `args` - The arguments, as a tuple such as `(&array,)`.
92    ///
93    /// # Returns
94    ///
95    /// The hook's result.
96    ///
97    /// # Errors
98    ///
99    /// Returns the error the hook raises, or a `TypeError` when a packed
100    /// function returns a value that does not convert to `R`.
101    ///
102    /// # Panics
103    ///
104    /// Panics if an object argument is not managed, such as an object built
105    /// on the stack: the hook may retain it.
106    ///
107    /// See also [`NativeFunction`].
108    pub fn call(&self, args: Args) -> Result<R> {
109        let raw = self.data.as_raw_ffi_any();
110        let result = if raw.type_index == TVMFFITypeIndex::kTVMFFIOpaquePtr as i32 {
111            // SAFETY: `from_any`'s caller vouches that the native function
112            // takes `Args` and returns `R`.
113            unsafe { args.call_native(raw.data_union.v_ptr) }
114        } else {
115            let function = self.data.downcast_ref::<Function>();
116            args.call_packed(function.expect("a hook is a native or packed function"))?
117        };
118        // A native function returns its error as its result.
119        if result.type_index() == TVMFFITypeIndex::kTVMFFIError as i32 {
120            return Err(result.try_into()?);
121        }
122        R::try_from(result).map_err(|_| Error::new(TYPE_ERROR, "Packed hook result type mismatch"))
123    }
124}
125
126impl<Args, R> Clone for NativeFunction<Args, R> {
127    fn clone(&self) -> Self {
128        Self {
129            data: self.data.clone(),
130            signature: PhantomData,
131        }
132    }
133}
134
135impl<Args, R> NativeFunction<Args, R> {
136    /// Read the hook that `value` holds: a non-null opaque pointer to a native
137    /// function, or a packed [`Function`].
138    ///
139    /// # Arguments
140    ///
141    /// * `value` - The hook, as its registry slot holds it.
142    ///
143    /// # Returns
144    ///
145    /// The hook, typed with `Args` and `R`.
146    ///
147    /// # Errors
148    ///
149    /// Returns a `TypeError` if `value` is neither a non-null opaque pointer
150    /// nor a [`Function`].
151    ///
152    /// # Safety
153    ///
154    /// A native function in `value` must take `Args` and return `R`, as the
155    /// code that registers it in the slot declares. A packed [`Function`] is
156    /// called through checked conversions and has no such requirement.
157    ///
158    /// See also [`NativeFunction`].
159    pub unsafe fn from_any(value: Any) -> Result<Self> {
160        // Every writer of a hook slot vouches for its signature, including
161        // writes through a container-valued column.
162        let raw = value.as_raw_ffi_any();
163        // SAFETY: `v_ptr` is the payload of an opaque pointer.
164        let native = raw.type_index == TVMFFITypeIndex::kTVMFFIOpaquePtr as i32
165            && !unsafe { raw.data_union.v_ptr }.is_null();
166        if !native && raw.type_index != TVMFFITypeIndex::kTVMFFIFunction as i32 {
167            let message = format!(
168                "Cannot convert from type `{}` to `NativeFunction`",
169                type_key_of_index(raw.type_index)
170            );
171            return Err(Error::new(TYPE_ERROR, &message));
172        }
173        Ok(Self {
174            data: value,
175            signature: PhantomData,
176        })
177    }
178
179    /// The hook as a registry slot holds it: the opaque pointer of a native
180    /// function, or the packed [`Function`].
181    ///
182    /// This is how a registry other than a type or enum attribute stores a
183    /// hook; [`from_any`](Self::from_any) reads it back.
184    ///
185    /// # Safety
186    ///
187    /// Every reader of the slot that stores the result calls it with exactly
188    /// `Args` and reads `R`: a native caller calls the function pointer
189    /// unchecked.
190    pub unsafe fn into_any(self) -> Any {
191        self.data
192    }
193}
194
195/// The argument tuples a [`NativeFunction`] takes: up to eight borrowed
196/// objects, managed references or [`Any`] values.
197///
198/// This trait is sealed.
199pub trait NativeArgs: sealed::NativeArgs {}
200
201impl<T: sealed::NativeArgs> NativeArgs for T {}
202
203mod sealed {
204    use super::*;
205
206    pub trait NativeArgs {
207        /// Call the native function `function` with these arguments.
208        ///
209        /// # Safety
210        ///
211        /// `function` is an `extern "C" fn(Args...) -> TVMFFIAny`.
212        unsafe fn call_native(self, function: *mut c_void) -> Any;
213
214        fn call_packed(self, function: &Function) -> Result<Any>;
215    }
216
217    /// An argument passed to a native function as itself: a pointer.
218    pub trait NativeArg: Copy {
219        /// The pointee, which a native function receives the address of.
220        type Target: 'static;
221
222        /// The argument as a packed function receives it.
223        fn to_any_view(&self) -> AnyView<'_>;
224    }
225
226    impl<T: DowncastRefFromObject + 'static> NativeArg for &T {
227        type Target = T;
228
229        #[inline(always)]
230        fn to_any_view(&self) -> AnyView<'_> {
231            // Panics on an unmanaged object.
232            AnyView::from_object(self.as_object())
233        }
234    }
235
236    impl NativeArg for &Any {
237        type Target = Any;
238
239        #[inline(always)]
240        fn to_any_view(&self) -> AnyView<'_> {
241            AnyView::from(*self)
242        }
243    }
244
245    /// The only value of the zero-sized `F`, for the adapter, which cannot
246    /// receive it.
247    ///
248    /// # Safety
249    ///
250    /// A value of `F` exists. `F` is `Copy`, so it has no drop and may be
251    /// duplicated: a zero-sized value that must stay unique, such as a token,
252    /// is not `Copy`.
253    #[inline(always)]
254    unsafe fn conjure<F: Copy>() -> F {
255        const {
256            assert!(
257                size_of::<F>() == 0,
258                "a native hook is built from a function or a closure that captures nothing"
259            )
260        };
261        // SAFETY: a zero-sized type has no bytes, so any value is initialized,
262        // and duplicating it is a copy (see above).
263        unsafe { std::mem::zeroed() }
264    }
265
266    /// The result of a native function as its caller owns it: the value, or
267    /// the error.
268    #[inline(always)]
269    fn into_raw<R: Into<Any>>(result: Result<R>) -> TVMFFIAny {
270        Any::into_raw_ffi_any(match result {
271            Ok(value) => value.into(),
272            Err(error) => Any::from(error),
273        })
274    }
275
276    macro_rules! impl_native_args {
277        ($($arg:ident $index:tt),*) => {
278            impl<$($arg: NativeArg),*> NativeArgs for ($($arg,)*) {
279                #[inline(always)]
280                unsafe fn call_native(self, function: *mut c_void) -> Any {
281                    // The function may retain an object argument, which must be managed.
282                    $(let _ = self.$index.to_any_view();)*
283                    // SAFETY: the caller passes a function of this signature,
284                    // which returns an owned value.
285                    unsafe {
286                        let function = std::mem::transmute::<
287                            *mut c_void,
288                            unsafe extern "C" fn($($arg),*) -> TVMFFIAny,
289                        >(function);
290                        Any::from_raw_ffi_any(function($(self.$index),*))
291                    }
292                }
293
294                #[inline(always)]
295                fn call_packed(self, function: &Function) -> Result<Any> {
296                    function.call_packed(&[$(self.$index.to_any_view()),*])
297                }
298            }
299        };
300    }
301
302    macro_rules! impl_native_fn {
303        ($($arg:ident $raw:ident),*) => {
304            /// Build a native hook from a function item or a closure that
305            /// captures nothing, with the C ABI adapter that native callers
306            /// call.
307            ///
308            /// The function takes the arguments as `call` passes them and
309            /// returns `Result<R>`; its error is the error the hook raises. A
310            /// hook reports failure through its `Result` and must not panic: a
311            /// panic aborts the process. A closure that captures a value does
312            /// not compile.
313            ///
314            /// See also [`NativeFunction`].
315            // The function takes borrows of any lifetime, so it cannot keep an
316            // argument past the call.
317            impl<F, $($arg: NativeArg,)* R: Into<Any>> From<F> for NativeFunction<($($arg,)*), R>
318            where
319                F: for<'a> Fn($(&'a $arg::Target),*) -> Result<R> + Copy + 'static,
320            {
321                fn from(_function: F) -> Self {
322                    extern "C" fn adapter<F, $($arg: NativeArg,)* R: Into<Any>>(
323                        $($raw: *const $arg::Target),*
324                    ) -> TVMFFIAny
325                    where
326                        F: for<'a> Fn($(&'a $arg::Target),*) -> Result<R> + Copy + 'static,
327                    {
328                        // SAFETY: `from` received a value of `F`.
329                        let function = unsafe { conjure::<F>() };
330                        // SAFETY: a native caller passes the address of a live
331                        // argument for the duration of the call, or null.
332                        $(let Some($raw) = (unsafe { $raw.as_ref() }) else {
333                            let message = "A native hook argument is null";
334                            return into_raw::<R>(Err(Error::new(TYPE_ERROR, message)));
335                        };)*
336                        // A panic aborts here rather than unwind into the caller.
337                        into_raw(function($($raw),*))
338                    }
339                    let adapter = adapter::<F, $($arg,)* R> as *mut c_void;
340                    Self { data: Any::from(adapter), signature: PhantomData }
341                }
342            }
343        };
344    }
345
346    impl_native_fn!();
347    impl_native_fn!(A0 a0);
348    impl_native_fn!(A0 a0, A1 a1);
349    impl_native_fn!(A0 a0, A1 a1, A2 a2);
350    impl_native_fn!(A0 a0, A1 a1, A2 a2, A3 a3);
351    impl_native_fn!(A0 a0, A1 a1, A2 a2, A3 a3, A4 a4);
352    impl_native_fn!(A0 a0, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5);
353    impl_native_fn!(A0 a0, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6);
354    impl_native_fn!(A0 a0, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6, A7 a7);
355
356    impl_native_args!();
357    impl_native_args!(A0 0);
358    impl_native_args!(A0 0, A1 1);
359    impl_native_args!(A0 0, A1 1, A2 2);
360    impl_native_args!(A0 0, A1 1, A2 2, A3 3);
361    impl_native_args!(A0 0, A1 1, A2 2, A3 3, A4 4);
362    impl_native_args!(A0 0, A1 1, A2 2, A3 3, A4 4, A5 5);
363    impl_native_args!(A0 0, A1 1, A2 2, A3 3, A4 4, A5 5, A6 6);
364    impl_native_args!(A0 0, A1 1, A2 2, A3 3, A4 4, A5 5, A6 6, A7 7);
365}