Skip to main content

rs_object

Attribute Macro rs_object 

Source
#[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)] 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>, 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); a field, own or inherited, cannot be writable. Every subtype must be immutable too.
  • s_eq_hash_kind = "TreeNode" - The 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 = 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 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");