1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
//! Rust bindings of TVM FFI, the open ABI and FFI for machine learning
//! systems.
//!
//! Values cross the boundary as [`Any`] and [`AnyView`]. Objects, such as
//! [`Array`], [`Map`], [`Tensor`] and types defined with [`rs_object`], are
//! reference counted and shared with C++ and Python. A [`Function`] is
//! callable from every language, and an [`Error`] raised in one arrives in
//! the others.
//!
//! # Examples
//!
//! ```standalone_crate
//! use tvm_ffi::{Array, Function, Result};
//!
//! let sum = |xs: Array<i64>| -> Result<i64> { Ok(xs.iter().sum()) };
//! Function::register_global_typed("my_ext.sum", sum, "Sum the elements.")?;
//!
//! let sum = Function::get_global("my_ext.sum")?;
//! let total = sum.call_tuple((Array::from_vec(vec![1_i64, 2, 3]),))?;
//! assert_eq!(i64::try_from(total)?, 6);
//! # Ok::<(), tvm_ffi::Error>(())
//! ```
//!
//! # FFI contracts
//!
//! Some guarantees rest on contracts every language keeps, which Rust cannot
//! check:
//!
//! * An `ffi.String` holds UTF-8, so [`String::as_str`] does not validate it.
//! * Types, functions and attributes register during static initialization,
//! such as in a [`static_init_block!`], before other threads read them:
//! readers of the runtime's tables take no lock.
//! * A type key describes the same type in every library that declares it;
//! see [`rs_object`].
//! * A [`TensorView`] received as a function argument is valid only during
//! the call, and so is an [`Any`] holding a `DLTensor*` converted from it
//! or from an [`AnyView`].
//! * A registered structural visit or mutate hook uses the visitor or
//! mutator only through its arguments, during the call, and does not keep
//! it.
// Lets macro-generated `::tvm_ffi` paths resolve inside this crate too.
extern crate self as tvm_ffi;
pub use tvm_ffi_sys;
pub use crate;
pub use crateBigInt;
pub use crateArray;
pub use crateList;
pub use crateMap;
pub use crateShape;
pub use crate;
pub use crateDLDataTypeExt;
pub use crateEnumRef;
pub use crate;
pub use crate;
pub use crate;
pub use crateModule;
pub use crate;
pub use cratestructural_map;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crateFunction;
pub use crate;
pub use crateOptional;
pub use craterun_static_init_blocks;
pub use crate;
pub use crate;
/// Generate runtime type dispatch from the `prefix_*` methods of an impl.
///
/// `#[dispatch(prefix, (First, Args...), Ret)]` on an inherent impl makes its
/// `prefix_*` methods handlers and adds a `dispatch(first, args...) ->
/// Option<Ret>` method. `dispatch` calls the first handler, in source order,
/// whose first parameter matches the runtime type of `first`, and returns
/// `None` when no handler matches. The macro also implements [`Dispatcher`]
/// for `&Self` or `&mut Self`, so the type can drive [`structural_walk`] and
/// the other traversals, whose engines call it and run their own default
/// recursion; no prefix has a reserved meaning. Handlers without an `inline`
/// attribute are marked `#[inline(always)]`.
///
/// # Arguments
///
/// * `prefix` - The handler name prefix; `describe` selects `describe_int`,
/// `describe_str` and so on.
/// * `(First, Args...)` - The complete input tuple. `First`, the value to
/// match, is `AnyView<'_>` or [`MutationView<'_>`], including aliases.
/// `Args` are passed through: each handler takes a leading prefix of them
/// without cloning, and need not take all of them.
/// * `Ret` - The result type. A handler's result is converted with
/// `Into<Ret>`. When both the handler's result and `Ret` are written
/// `Result<..>`, the success value is converted instead, so a
/// `Result<UnchangedOr<MyPair>>` handler fits a `Result<UnchangedOr<Any>>`
/// dispatcher.
///
/// # Handlers
///
/// A handler's first parameter selects what it matches, as for
/// [`match_any!`]: an owned FFI value such as `i64` or `Array<Any>`, converted
/// strictly; `&Type` (such as `&Array<i64>` or `&tvm_ffi::String`) or
/// `&NodeObj`, which borrow the value or the object node in place without
/// changing a reference count; `MutationView<'_, T>`,
/// which keeps the in-place mode; or `AnyView<'_>`, which
/// matches every value and must be the last handler.
///
/// Only the outer `None` means that no handler matched: a handler error, or a
/// `None` inside `Ret`, is final. Handlers share one receiver, `&self` or
/// `&mut self`, and the same method generics and bounds; shared generics must
/// occur in the receiver, the input tuple or `Ret`. Use the same lifetime name
/// in an input and `Ret` to return a borrow of that input; elided output
/// lifetimes borrow the receiver. Handler-level `cfg` attributes are not
/// supported; configure the whole impl instead. Generate one dispatcher per
/// type; when inference is ambiguous, give the expected result type.
///
/// # Examples
///
/// ```
/// use tvm_ffi::{dispatch, AnyView};
///
/// struct Describer;
///
/// #[dispatch(describe, (AnyView<'_>,), String)]
/// impl Describer {
/// fn describe_int(&self, value: i64) -> String {
/// format!("integer {value}")
/// }
///
/// fn describe_str(&self, value: &tvm_ffi::String) -> String {
/// format!("string {}", value.as_str())
/// }
/// }
///
/// let text = tvm_ffi::String::from("hi");
/// assert_eq!(Describer.dispatch(AnyView::from(&1_i64)).as_deref(), Some("integer 1"));
/// assert_eq!(Describer.dispatch(AnyView::from(&text)).as_deref(), Some("string hi"));
/// assert_eq!(Describer.dispatch(AnyView::from(&1.5_f64)), None);
/// ```
///
/// [`MutationView<'_>`]: crate::MutationView
/// [`Dispatcher`]: crate::Dispatcher
/// [`structural_walk`]: crate::structural_walk
pub use dispatch;
/// Match the runtime type of a value, the way `match` matches an enum.
///
/// The value is an [`Any`], an [`AnyView`], a managed reference or a
/// [`MutationView`]. It is evaluated once and taken by value; write `&value`
/// to keep it. Arms are tried in order, and the first arm whose type matches
/// runs; a guard that is false moves on to the next arm. The last arm must be
/// an unguarded `_ => ...`, since new types can be registered at any time.
///
/// * `Type(name)` binds an owned value of `Type`, such as `i64` or
/// `Array<Any>`.
/// * `Type(ref name)` borrows a managed reference, and `NodeObj(ref name)`
/// borrows the object node, without changing its reference count.
/// * `MutationView<Type>(name)` moves the in-place mode into a
/// typed view.
///
/// Matching is strict: an `i64` arm does not match a stored `f64`, and a value
/// is never truncated. Type aliases and qualified paths may name `Type`. Typed
/// `MutationView` arms do not match a `Map`, including a nested one; use
/// `MutationView<Any>` for those. Ordinary `Map<K, V>` arms do match.
///
/// While an arm borrows the value, it must not modify an `ffi.List` or
/// `ffi.Dict` that holds the value, which may be the borrow's only owner.
///
/// # Examples
///
/// ```
/// use tvm_ffi::{match_any, Any, Array};
///
/// fn kind(value: &Any) -> String {
/// match_any! {
/// value {
/// i64(n) => format!("integer {n}"),
/// tvm_ffi::String(s) => format!("string {}", s.as_str()),
/// Array<Any>(arr) => format!("array of {} items", arr.len()),
/// _ => "something else".to_string(),
/// }
/// }
/// }
///
/// assert_eq!(kind(&Any::from(42_i64)), "integer 42");
/// assert_eq!(kind(&Any::from(Array::from_vec(vec![1_i64, 2, 3]))), "array of 3 items");
/// assert_eq!(kind(&Any::from(1.5_f64)), "something else");
/// ```
pub use match_any;
/// Define an object type in Rust that every language can use.
///
/// `#[rs_object(type_key = "type.Key", options...)]` registers the struct as an object
/// type with the reflection of every field, so that structural equality and
/// hashing, `repr`, deep copy and Python see the fields. The first field,
/// `base_`, is the parent type's object, embedded at the start of the struct:
/// `base_: Object` for a type under `ffi.Object`; the trailing `_` leaves
/// `base` free for a reflected field. Declare the managed reference with
/// [`#[derive(ObjectRef)]`](derive::ObjectRef).
///
/// The macro adds to the struct:
///
/// * `#[repr(C)]` and `Deref` to the parent's object, so `obj.field` reads the
/// fields of both.
/// * `MyPairObj::new(base_, fields...)`, which takes the fields in order: a
/// scalar (`bool`, an integer or a float) as its own type, so that a literal
/// infers as it, and any other field as `impl Into<T>`. This is the
/// object-level allocator, which sees only tokens and so cannot tell an
/// object reference from a value; a constructor on the reference takes an
/// object reference as [`impl IntoArg<T>`](IntoArg), as the
/// ones `tvm-ffi-stubgen` generates do.
///
/// # Arguments
///
/// * `type_key = "type.Key"` - The type key, required.
/// * `final` - The type has no subtypes.
/// * `immutable` - Shared objects of the type are never mutated, so its
/// references cross threads when its fields can
/// ([`ImmutableObject`](crate::object::ImmutableObject)); a field, own or
/// inherited, cannot be `writable`. Every subtype must be `immutable` too.
/// * `s_eq_hash_kind = "TreeNode"` - The [`SEqHashKind`](crate::reflection::SEqHashKind) of structural
/// equality; by default the parent's. Structural equality and hashing see
/// the fields only when the type or an ancestor has one, and otherwise fail
/// with a `TypeError`.
/// * `child_slots = N`, `child_slots_can_overflow = bool` - Type indices kept
/// for subtypes; 0 and `true` by default.
/// * `reflection = path` - A `fn(&mut ObjectDef<Self>)` that registers the
/// type's methods, under the constraints of
/// [`ObjectDef`](crate::reflection::ObjectDef).
/// * `crate = path` - Where the generated code finds tvm-ffi, for a crate that
/// depends on it only through a re-export; by default `tvm_ffi`.
///
/// A field takes `#[reflect(writable, seq_hash_ignore, ...)]` for the
/// [`FieldFlags`](crate::reflection::FieldFlags) of those names, and `name = "..."` or `doc = "..."` to
/// register it under another name or with a doc string, by default its `///`
/// comment. As a C++ `def_rw` field, a `writable` field can be replaced
/// through reflection, such as from Python, while the object is shared.
///
/// # Requirements
///
/// A field's type must implement `AnyCompatible` and `Clone`; an `init_off`
/// field's type must take all-zero bytes as a value. An optional field is an
/// `Option` of an object reference or an [`Optional`] of any other value. The parent's object must
/// implement `ShallowCopy` and `UnsafeInit`, as `rs_object` types and
/// `#[object(rs_parent)]` bindings, such as the non-final ones `tvm-ffi-stubgen`
/// generates, do.
///
/// # Registration
///
/// The type registers when its library loads, as a C++ type does in a static
/// init block, with its fields, methods, `__ffi_new__` and, unless the methods
/// define it, `__ffi_init__`; under a binding whose library is not loaded
/// yet, it registers on its first `type_index()` after that library loads. A
/// key already registered, by another library or a binding, must describe the
/// same type: `type_index()` checks its parent, depth and size, not its
/// fields.
///
/// Registrations from one library hold that library's lock, so they do not
/// race each other; libraries that each link tvm-ffi have a lock each. The
/// runtime's type table is not locked otherwise, and its readers take no
/// lock: as for C++, types register during static initialization, before
/// other threads use them or load a library that registers types. A type
/// that registers lazily, under a binding loaded later, must take its first
/// `type_index()` under the same rule.
///
/// # Examples
///
/// ```standalone_crate
/// use tvm_ffi::derive::ObjectRef;
/// use tvm_ffi::{rs_object, Object, ObjectArc};
///
/// #[rs_object(type_key = "my_ext.MyPair", final)]
/// pub struct MyPairObj {
/// base_: Object,
/// pub first: i64,
/// #[reflect(seq_hash_ignore)]
/// pub second: tvm_ffi::String,
/// }
///
/// #[derive(Clone, ObjectRef)]
/// pub struct MyPair {
/// data: ObjectArc<MyPairObj>,
/// }
///
/// let pair = MyPair::from_object(MyPairObj::new(Object::new(), 1, "one"));
/// assert_eq!(pair.first, 1);
/// assert_eq!(pair.second.as_str(), "one");
/// ```
pub use rs_object;
pub use TVMFFITypeIndex as TypeIndex;
pub use ;