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}