#[rs_object]Expand description
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)].
The macro adds to the struct:
#[repr(C)]andDerefto the parent’s object, soobj.fieldreads 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 asimpl 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 asimpl IntoArg<T>, as the onestvm-ffi-stubgengenerates 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); a field, own or inherited, cannot bewritable. Every subtype must beimmutabletoo.s_eq_hash_kind = "TreeNode"- TheSEqHashKindof 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 aTypeError.child_slots = N,child_slots_can_overflow = bool- Type indices kept for subtypes; 0 andtrueby default.reflection = path- Afn(&mut ObjectDef<Self>)that registers the type’s methods, under the constraints ofObjectDef.crate = path- Where the generated code finds tvm-ffi, for a crate that depends on it only through a re-export; by defaulttvm_ffi.
A field takes #[reflect(writable, seq_hash_ignore, ...)] for the
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
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");