This is an automated email from the ASF dual-hosted git repository.
tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/main by this push:
new a7747be2 [DOC] Clarify named managed references (#812)
a7747be2 is described below
commit a7747be2b4b7d3f1509e5c470248bd195547887c
Author: Tianqi Chen <[email protected]>
AuthorDate: Fri Sep 25 11:20:54 2026 -0400
[DOC] Clarify named managed references (#812)
Clarify how named managed references manage object lifetimes, define
their interfaces, and constrain their underlying objects. Explain the
C++ reference-class and Rust newtype patterns using `Array<T>` and
`ArrayObj`.
Correct the Rust `ObjectRef` description and distinguish the
`Object`/`ObjectRef` derive macros from the `ObjectCore`/`ObjectRefCore`
traits.
---
docs/concepts/object_and_class.rst | 16 +++++++++++++---
docs/guides/rust_lang_guide.md | 7 +++++++
docs/reference/rust/index.rst | 3 ++-
include/tvm/ffi/object.h | 12 +++++++++++-
rust/tvm-ffi/src/object.rs | 5 +++--
5 files changed, 36 insertions(+), 7 deletions(-)
diff --git a/docs/concepts/object_and_class.rst
b/docs/concepts/object_and_class.rst
index 9d0d67ce..9a4fa8d6 100644
--- a/docs/concepts/object_and_class.rst
+++ b/docs/concepts/object_and_class.rst
@@ -93,9 +93,19 @@ It declares a class ``MyObjectObj`` that inherits from
:cpp:class:`~tvm::ffi::Ob
/*parent_type=*/ffi::Object);
};
-**Managed reference**. Optionally, a managed reference class can be defined by
inheriting
-from :cpp:class:`~tvm::ffi::ObjectRef` and using one of the following macros
to define the methods.
-Define its constructor by wrapping the :cpp:func:`tvm::ffi::make_object`
function.
+**Named managed reference**. :cpp:class:`~tvm::ffi::ObjectRef` is the base
class for named,
+managed references to TVM-FFI objects. Each reference holds an
``ObjectPtr<Object>``, which
+manages the underlying object’s lifetime through reference counting. Use
``operator->`` to
+access data members and member functions of the underlying object.
+
+A reference class can define its own constructors, member functions, and
operators, and
+inherit from other reference classes to share and specialize its interface. It
can also
+impose additional constraints on the underlying object. For example,
``Array<T>`` uses
+``ArrayObj`` as its underlying object type while constraining the array’s
element type to ``T``.
+
+Optionally, define a named managed reference class by inheriting from
+:cpp:class:`~tvm::ffi::ObjectRef` and using one of the following macros. A
constructor that
+creates the underlying object can wrap :cpp:func:`tvm::ffi::make_object`.
:c:macro:`TVM_FFI_DEFINE_OBJECT_REF_METHODS_NULLABLE(TypeName, ParentType,
ObjectName) <TVM_FFI_DEFINE_OBJECT_REF_METHODS_NULLABLE>`
Define a nullable reference class.
diff --git a/docs/guides/rust_lang_guide.md b/docs/guides/rust_lang_guide.md
index 5d01101e..015dea10 100644
--- a/docs/guides/rust_lang_guide.md
+++ b/docs/guides/rust_lang_guide.md
@@ -65,6 +65,13 @@ export LD_LIBRARY_PATH=$(tvm-ffi-config
--libdir):$LD_LIBRARY_PATH
## Basic Usage
+**Named managed reference**. A named managed reference follows the newtype
pattern around
+`ObjectArc<T>`, which manages the underlying object’s lifetime through
reference counting.
+Define methods and associated functions on the named type, and implement
traits to provide
+shared interfaces. The named type can also impose additional constraints on
the underlying object.
+For example, `Array<T>` holds an `ObjectArc<ArrayObj>` while constraining the
array’s
+element type to `T`. Named reference types implement `ObjectRefCore` for
shared reference operations.
+
### Loading a Module
Load a compiled TVM FFI module and call its functions:
diff --git a/docs/reference/rust/index.rst b/docs/reference/rust/index.rst
index 12a71be9..b4582044 100644
--- a/docs/reference/rust/index.rst
+++ b/docs/reference/rust/index.rst
@@ -37,4 +37,5 @@ The Rust API is organized into three crates:
* - 📦 `tvm-ffi-sys <generated/tvm_ffi_sys/index.html>`_
- Low-level unsafe bindings to the C API.
* - 📦 `tvm-ffi-macros <generated/tvm_ffi_macros/index.html>`_
- - Procedural macros for deriving Object and ObjectRef traits.
+ - The ``Object`` and ``ObjectRef`` derive macros implement the
``ObjectCore`` and
+ ``ObjectRefCore`` traits, respectively.
diff --git a/include/tvm/ffi/object.h b/include/tvm/ffi/object.h
index 722dce3a..81ac2b10 100644
--- a/include/tvm/ffi/object.h
+++ b/include/tvm/ffi/object.h
@@ -811,7 +811,17 @@ class WeakObjectPtr {
template <typename T, typename = void>
class Optional;
-/*! \brief Base class of all object reference */
+/*!
+ * \brief ObjectRef is the base class for named, managed references to TVM-FFI
objects.
+ *
+ * Each reference holds an `ObjectPtr<Object>`, which manages the underlying
object’s lifetime
+ * through reference counting. Use `operator->` to access data members and
member functions
+ * of the underlying object.
+ *
+ * A reference class can define its own constructors, member functions, and
operators, and
+ * inherit from other reference classes to share and specialize its interface.
It can also
+ * impose additional constraints on the underlying object.
+ */
class ObjectRef {
public:
/*! \brief default constructor */
diff --git a/rust/tvm-ffi/src/object.rs b/rust/tvm-ffi/src/object.rs
index d690a64b..8b19b5f0 100644
--- a/rust/tvm-ffi/src/object.rs
+++ b/rust/tvm-ffi/src/object.rs
@@ -307,9 +307,10 @@ pub trait ObjectRefCast: ObjectRefCore + AnyCompatible {
impl<T: ObjectRefCore + AnyCompatible> ObjectRefCast for T {}
-/// Base class for ObjectRef
+/// A generic managed reference to a TVM-FFI object.
///
-/// This class is used to store the data of the ObjectRef
+/// Holds an `ObjectArc<Object>` that manages the underlying object's lifetime
+/// through reference counting.
#[repr(C)]
#[derive(ObjectRef, Clone)]
pub struct ObjectRef {
