Object/Node

Object是所有对象容器的基类。
Node是runtime::Object的别名。

Objecgt子类的对象应该声明以下静态constexpr字段。

  • _type_index

    1. 对象的静态类型索引，并非当前对象的类型索引，旨在被子类作为默认值使用。如果设置为TypeIndex::kDynamic，类型索引将在运行时分配。<br />      运行时类型索引可以通过ObjectType::TypeIndex()访问。

  • _type_key

    1. type类型的唯一字符串标识符。

  • _type_final

    1. 类型是否为终端类型(在对象系统中没有该类型的子类)，该字段由marco TVM_DECLARE_FINAL_OBJECT_INFO自动设置。<br />      对于终端对象类型T的子类，使用make_object构造它仍然是可以的，但IsInstance检查只会显示对象类型为T（而不是子类）。

以下两个字段是可以被子类化的基类所必需的:

  • _type_child_slots:

    1. 为子类保留的类型索引槽的数量。用于IsInstance中类型检查的运行时优化。<br />      如果一个对象的type_index在[type_index, type_index + _type_child_slots]的范围内，则可以快速判定该对象为当前对象类的子类，如果不是，则使用回退机制检查全局类型表。<br />      建议：设置为估计需要的子类数量。

  • _type_child_slots_can_overflow:

    1. 即使子类的数量超过了_type_child_slots，我们是否可以添加额外的子类。将使用一个后备机制来检查全局类型表。<br />      建议：如果我们知道确切的子代数量，为了优化运行速度，将其设置为false。

用于在对象中声明辅助函数的两个宏:

  • TVM_DECLARE_BASE_OBJECT_INFO 用于可以被子类化的对象类.
  • TVM_DECLARE_FINAL_OBJECT_INFO 用于不可以被子类化的对象类。

新的对象可以使用make_object函数来创建，这将自动设置对象的type_index和deleter。

部分源码如下：

  1. class Object {
  2.  public:
  4.   /*!
  5.    * Check if the object is an instance of TargetType.
  6.    * \tparam TargetType The target type to be checked.
  7.    * \return Whether the target type is true.
  8.    */
  9.   template<typename TargetType>
  10.   inline bool IsInstance() const;
  12.   static constexpr const char* _type_key = "Object";
  14.   // Default object type properties for sub-classes
  15.   static constexpr bool _type_final = false;
  16.   static constexpr uint32_t _type_child_slots = 0;
  17.   static constexpr bool _type_child_slots_can_overflow = true;
  18.   // NOTE: the following field is not type index of Object
  19.   // but was intended to be used by sub-classes as default value.
  20.   // The type index of Object is TypeIndex::kRoot
  21.   static constexpr uint32_t _type_index = TypeIndex::kDynamic;
  23.  protected:
  24.   // The fields of the base object cell.
  25.   /*! \brief Type index(tag) that indicates the type of the object. */
  26.   uint32_t type_index_{0};
  28.   /*! \brief The internal reference counter */
  29.   RefCounterType ref_counter_{0};
  31.   /*!
  32.    * \brief deleter of this object to enable customized allocation.
  33.    * If the deleter is nullptr, no deletion will be performed.
  34.    * The creator of the object must always set the deleter field properly.
  35.    */
  36.   FDeleter deleter_ = nullptr;    
  38.  private:
  39.   /*!
  40.    * \return The usage count of the cell.
  41.    * \note We use stl style naming to be consistent with known API in shared_ptr.
  42.    */
  43.   inline int use_count() const;
  44.   /*!
  45.    * \brief Check of this object is derived from the parent.
  46.    * \param parent_tindex The parent type index.
  47.    * \return The derivation results.
  48.    */
  49.   TVM_DLL bool DerivedFrom(uint32_t parent_tindex) const;
  51. };


ObjectPtr

ObjectPtr是Object的自定义智能指针。
它是一个模板类。部分源码如下：

  1. template <typename T>
  2. class ObjectPtr {
  3. ...
  4. public:
  5.   /*!
  6.    * \return Get the content of the pointer
  7.    */
  8.   T* get() const {
  9.     return static_cast<T*>(data_);
  10.   }
  11.   /*!
  12.    * \return The pointer
  13.    */
  14.   T* operator->() const {
  15.     return get();
  16.   }
  17.   /*!
  18.    * \return The reference
  19.    */
  20.   T& operator*() const {  // NOLINT(*)
  21.     return *get();
  22.   }   
  23. private:
  24.   /*! \brief internal pointer field */
  25.   Object* data_{nullptr};
  26. ...
  27. }

它唯一的字段是Object data. 一般的，T是Object的子类。它的函数get()可以将data变成T。

ObjectRef

ObjectRef是所有对象引用的基类。
部分源码如下：

  1. /*! \brief Base class of all object reference */
  2. class ObjectRef {
  3.  public:
  5.   /*!
  6.    * \brief Comparator
  7.    * \param other Another object ref.
  8.    * \return the compare result.
  9.    */
  10.   bool same_as(const ObjectRef& other) const {
  11.     return data_ == other.data_;
  12.   }
  14.   /*! \return whether the expression is null */
  15.   bool defined() const {
  16.     return data_ != nullptr;//注意，在ObjectPtr中重载了!=,所以这里是没有问题的。  
  17.   }
  18.   /*! \return the internal object pointer */
  19.   const Object* get() const {
  20.     return data_.get();
  21.   }
  22.   /*! \return the internal object pointer */
  23.   const Object* operator->() const {
  24.     return get();
  25.   }
  27.   /*!
  28.    * \brief Try to downcast the internal Object to a
  29.    *  raw pointer of a corresponding type.
  30.    *
  31.    *  The function will return a nullptr if the cast failed.
  32.    *
  33.    * if (const Add *add = node_ref.As<Add>()) {
  34.    *   // This is an add node
  35.    * }
  36.    * \tparam ObjectType the target type, must be a subtype of Object/
  37.    */
  38.   template <typename ObjectType>
  39.   inline const ObjectType* as() const;
  41.   /*! \brief type indicate the container type. */
  42.   using ContainerType = Object;
  44.  protected:
  45.   /*! \brief Internal pointer that backs the reference. */
  46.   ObjectPtr<Object> data_;
  48.   /*!
  49.    * \brief Internal helper function downcast a ref without check.
  50.    * \note Only used for internal dev purposes.
  51.    * \tparam T The target reference type.
  52.    * \return The casted result.
  53.    */
  54.   template<typename T>
  55.   static T DowncastNoCheck(ObjectRef ref) {
  56.     return T(std::move(ref.data_));
  57.   }
  59.   /*!
  60.    * \brief Internal helper function get data_ as ObjectPtr of ObjectType.
  61.    * \note only used for internal dev purpose.
  62.    * \tparam ObjectType The corresponding object type.
  63.    * \return the corresponding type.
  64.    */
  65.   template<typename ObjectType>
  66.   static ObjectPtr<ObjectType> GetDataPtr(const ObjectRef& ref) {
  67.     return ObjectPtr<ObjectType>(ref.data_.data_);
  68.   }
  70. };

该类含有一个字段是ObjectPtr data_;

几个重要函数

  1. // 判断某个Object实例是否是某类的的实例
  2. template<typename TargetType>
  3. inline bool Object::IsInstance() const {
  4.   const Object* self = this;
  5.   // NOTE: the following code can be optimized by
  6.   // compiler dead-code elimination for already known constants.
  7.   if (self != nullptr) {
  8.     // Everything is a subclass of object.
  9.     if (std::is_same<TargetType, Object>::value) return true;
  10.     if (TargetType::_type_final) {
  11.       // if the target type is a final type
  12.       // then we only need to check the equivalence.
  13.       return self->type_index_ == TargetType::RuntimeTypeIndex();
  14.     } else {
  15.       // if target type is a non-leaf type
  16.       // Check if type index falls into the range of reserved slots.
  17.       uint32_t begin = TargetType::RuntimeTypeIndex();
  18.       // The condition will be optimized by constant-folding.
  19.       if (TargetType::_type_child_slots != 0) {
  20.         uint32_t end = begin + TargetType::_type_child_slots;
  21.         if (self->type_index_ >= begin && self->type_index_ < end) return true;
  22.       } else {
  23.         if (self->type_index_ == begin) return true;
  24.       }
  25.       if (!TargetType::_type_child_slots_can_overflow) return false;
  26.       // Invariance: parent index is always smaller than the child.
  27.       if (self->type_index_ < TargetType::RuntimeTypeIndex()) return false;
  28.       // The rare slower-path, check type hierachy.
  29.       return self->DerivedFrom(TargetType::RuntimeTypeIndex());
  30.     }
  31.   } else {
  32.     return false;
  33.   }
  34. }
  36. // 尝试将ObjectRef类对象的内部Object转为指定类型的指针
  37. template <typename ObjectType>
  38. inline const ObjectType* ObjectRef::as() const {
  39.   if (data_ != nullptr &&
  40.       data_->IsInstance<ObjectType>()) {
  41.     return static_cast<ObjectType*>(data_.get());
  42.   } else {
  43.     return nullptr;
  44.   }
  45. }
  47. // 从Object类指针获得其引用类型指针
  48. template <typename RefType, typename ObjType>
  49. inline RefType GetRef(const ObjType* ptr) {
  50.   static_assert(std::is_base_of<typename RefType::ContainerType, ObjType>::value,
  51.                 "Can only cast to the ref of same container type");
  52.   return RefType(ObjectPtr<Object>(const_cast<Object*>(static_cast<const Object*>(ptr))));
  53. }
  55. template <typename BaseType, typename ObjType>
  56. inline ObjectPtr<BaseType> GetObjectPtr(ObjType* ptr) {
  57.   static_assert(std::is_base_of<BaseType, ObjType>::value,
  58.                 "Can only cast to the ref of same container type");
  59.   return ObjectPtr<BaseType>(static_cast<Object*>(ptr));
  60. }
  62. template <typename SubRef, typename BaseRef>
  63. inline SubRef Downcast(BaseRef ref) {
  64.   CHECK(ref->template IsInstance<typename SubRef::ContainerType>())
  65.       << "Downcast from " << ref->GetTypeKey() << " to "
  66.       << SubRef::ContainerType::_type_key << " failed.";
  67.   return SubRef(std::move(ref.data_));
  68. }


Demo

  1. // Create a base object
  2.   class ObjBase: public Object {
  3.    public:
  4.     // object fields
  5.     int field0;
  6.     // object properties
  7.     static constexpr const uint32_t _type_index = TypeIndex::kDynamic;
  8.     static constexpr const char _type_key = "test.ObjBase ";
  9.     TVM_DECLARE_BASE_OBJECT_INFO(ObjBase , Object);
  10.   };
  12.   class ObjLeaf : public ObjBase {
  13.    public:
  14.     // fields
  15.     int child_field0;
  16.     // object properties
  17.     static constexpr const uint32_t _type_index = TypeIndex::kDynamic;
  18.     static constexpr const char _type_key = "test.ObjLeaf ";
  19.     TVM_DECLARE_BASE_OBJECT_INFO(ObjLeaf , ObjBase);
  20.   };
  22.   // The following code should be put into a cc file.
  23.   TVM_REGISTER_OBJECT_TYPE(ObjBase);
  24.   TVM_REGISTER_OBJECT_TYPE(ObjLeaf);
  26.   // Usage example.
  27.   void TestObjects() {
  28.     // create an object
  29.     ObjectRef leaf_ref(make_object<ObjLeaf>());
  30.     // cast to a specific instance
  31.     const ObjLeaf *leaf_ptr = leaf_ref.as<ObjLeaf>();
  32.     CHECK(leaf_ptr != nullptr);
  33.     // can also cast to the base class.
  34.     CHECK(leaf_ref.as<ObjBase>() != nullptr);
  35.   }