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}