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
/*
* 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.
*/
//! The derive macros of object types and object references.
/// Bind an object type that another library, usually C++, registers: derive
/// [`ObjectCore`](crate::ObjectCore) for a `#[repr(C)]` object struct whose
/// first field is its parent, so that a pointer to the object is one to its
/// parent. Define a new type in Rust with [`rs_object`](macro@crate::rs_object)
/// instead.
///
/// Without `register` or `type_index`, `type_index()` takes the index the
/// defining library registered for the key, and panics if that library is not
/// loaded yet, so a binding never registers a key with the wrong child slots.
/// Such a panic is final: `type_index()` of the type, and of every type under
/// it, keeps panicking after the library loads, so call it only once the
/// library is loaded. It also panics unless the registered key has the type's
/// parent and depth and, when the type table records a size, a size no
/// smaller than the type's.
///
/// A binding that declares only part of its object must not be constructed:
/// keep its fields private.
///
/// # Options
///
/// `#[object(...)]` takes a comma-separated list, as in
/// `#[object(type_key = "ffi.String", unsafe type_index = TypeIndex::kTVMFFIStr)]`:
///
/// * `type_key = "..."` - The type key; required.
/// * `unsafe type_index = expr` - A static index instead of the registered
/// one; the `unsafe` marks the caller's promise that the runtime gives that
/// index to this type.
/// * `final` - The type has no subtypes, as C++ `_type_final`.
/// * `immutable` - Implement
/// [`ImmutableObject`](crate::object::ImmutableObject), as for a C++ type
/// not registered as `_type_mutable`; every subtype must be immutable too.
/// * `rs_parent` - Implement `ShallowCopy` and
/// [`UnsafeInit`](crate::reflection::UnsafeInit), so an `rs_object` can
/// derive from the type. Each field other than the parent must be `Clone`
/// and implement [`AnyCompatible`](crate::AnyCompatible), be an
/// [`Any`](crate::Any) or have no drop glue.
/// * `register` - The type is defined here: register its key under its
/// parent when the library loads, as `rs_object` does.
/// * `child_slots = N`, `child_slots_can_overflow = bool` - Type indices kept
/// for subtypes, as C++ `_type_child_slots` and
/// `_type_child_slots_can_overflow`; 0 and `true` by default. Needs
/// `register`.
/// * `s_eq_hash_kind = "TreeNode"` - The
/// [`SEqHashKind`](crate::reflection::SEqHashKind) of structural equality;
/// by default the parent's.
/// * `reflection = path` - A `fn(&mut ObjectDef<Self>)` that registers the
/// type's methods.
///
/// `s_eq_hash_kind`, `reflection` and field `#[reflect(...)]`, as
/// [`rs_object`](macro@crate::rs_object) takes it, need `register` and no
/// `type_index`.
pub use Object;
/// Declare an object reference: the managed, reference-counted handle to an
/// object type, as `Arc<FooObj>` is to `FooObj`.
///
/// The struct holds one field, `ObjectArc<FooObj>`. The derive implements
/// [`ObjectRefCore`](crate::ObjectRefCore), the default
/// [`ObjectRefAnyCompatible`](crate::object::ObjectRefAnyCompatible) (conversions to
/// and from [`Any`](crate::Any), in-place downcasts, typed function
/// arguments), the upcast to [`ObjectRef`](crate::object::ObjectRef),
/// `Deref<Target = FooObj>` for field reads, `Debug`, `Display` (the runtime
/// `repr`, as [`AnyView`](crate::AnyView) formats it), and a private
/// `fn from_object(object: FooObj) -> Self` for the type's constructors.
///
/// # Options
///
/// `#[object_ref(...)]` takes:
///
/// * `parent = Ref` - The reference to the parent's object, or to a further
/// ancestor's; `Self` converts into it. The object type must embed that
/// object type through its chain of parents
/// ([`ObjectDerivesFrom`](crate::object::ObjectDerivesFrom)), so a wrong parent does not
/// compile. Any other ancestor takes
/// [`impl_object_ref_upcast!`](crate::impl_object_ref_upcast).
/// * `unsafe parent = Ref` - As `parent`, for a reference that promises more
/// than its object type: a generic one (`Array<T>`, `Map<K, V>`,
/// `Optional<T>`) or one with a custom `ObjectRefAnyCompatible`. The caller
/// promises that every value of `Self` is a valid `Ref`; `parent` alone
/// does not compile for such a reference.
/// * `skip_deref` - No `Deref`, for a reference whose object is internal.
/// * `skip_debug` - `Debug` is written by hand.
/// * `skip_display` - `Display` is written by hand.
/// * `skip_any_compatible` - `ObjectRefAnyCompatible` is written by hand,
/// for a typed reference with a stricter check or fallback conversions.
/// * `crate = path` - Where the generated code finds tvm-ffi, as for
/// [`rs_object`](macro@crate::rs_object).
///
/// # Examples
///
/// ```standalone_crate
/// use tvm_ffi::derive::ObjectRef;
/// use tvm_ffi::{rs_object, Object, ObjectArc};
///
/// #[rs_object(type_key = "my_ext.MyPair")]
/// pub struct MyPairObj {
/// base_: Object,
/// pub first: i64,
/// pub second: i64,
/// }
///
/// #[derive(Clone, ObjectRef)]
/// pub struct MyPair {
/// data: ObjectArc<MyPairObj>,
/// }
///
/// #[rs_object(type_key = "my_ext.MyTriple", final)]
/// pub struct MyTripleObj {
/// base_: MyPairObj,
/// pub third: i64,
/// }
///
/// #[derive(Clone, ObjectRef)]
/// #[object_ref(parent = MyPair)]
/// pub struct MyTriple {
/// data: ObjectArc<MyTripleObj>,
/// }
///
/// impl MyTriple {
/// pub fn new(first: i64, second: i64, third: i64) -> Self {
/// let pair = MyPairObj::new(Object::new(), first, second);
/// Self::from_object(MyTripleObj::new(pair, third))
/// }
/// }
///
/// let triple = MyTriple::new(1, 2, 3);
/// assert_eq!(triple.first + triple.third, 4);
/// let _pair: MyPair = triple.into();
/// ```
///
/// A `MyPairObj` does not embed an `ArrayObj`, so it cannot claim `Array` as
/// its parent:
///
/// ```compile_fail,E0277
/// use tvm_ffi::derive::ObjectRef;
/// use tvm_ffi::{rs_object, Array, Object, ObjectArc};
///
/// #[rs_object(type_key = "my_ext.MyPair")]
/// pub struct MyPairObj {
/// base_: Object,
/// pub first: i64,
/// }
///
/// #[derive(Clone, ObjectRef)]
/// #[object_ref(unsafe parent = Array<i64>)]
/// pub struct MyPair {
/// data: ObjectArc<MyPairObj>,
/// }
/// ```
pub use ObjectRef;