mxnet::runtime::Object Class Reference

base class of all object containers. More...

#include <object.h>

Inheritance diagram for mxnet::runtime::Object:

Collaboration diagram for mxnet::runtime::Object:

Public Types
typedef void(*	FDeleter) (Object *self)
	Object deleter. More...
using	RefCounterType = std::atomic< int32_t >

Public Member Functions
uint32_t	type_index () const
std::string	GetTypeKey () const
size_t	GetTypeKeyHash () const
template<typename TargetType >
bool	IsInstance () const
	Object ()
	Object (const Object &other)
	Object (Object &&other)
Object &	operator= (const Object &other)
Object &	operator= (Object &&other)

Static Public Member Functions
static MXNET_DLL std::string	TypeIndex2Key (uint32_t tindex)
	Get the type key of the corresponding index from runtime. More...
static MXNET_DLL size_t	TypeIndex2KeyHash (uint32_t tindex)
	Get the type key hash of the corresponding index from runtime. More...
static MXNET_DLL uint32_t	TypeKey2Index (const std::string &key)
	Get the type index of the corresponding key from runtime. More...
static uint32_t	_GetOrAllocRuntimeTypeIndex ()
static uint32_t	RuntimeTypeIndex ()

Static Public Attributes
static constexpr const char *	_type_key = "Object"
static constexpr bool	_type_final = false
static constexpr uint32_t	_type_child_slots = 0
static constexpr bool	_type_child_slots_can_overflow = true
static constexpr uint32_t	_type_index = TypeIndex::kDynamic

Protected Member Functions
void	IncRef ()
	developer function, increases reference counter. More...
void	DecRef ()
	developer function, decrease reference counter. More...

Static Protected Member Functions
static MXNET_DLL uint32_t	GetOrAllocRuntimeTypeIndex (const std::string &key, uint32_t static_tindex, uint32_t parent_tindex, uint32_t type_child_slots, bool type_child_slots_can_overflow)
	Get the type index using type key. More...

Protected Attributes
uint32_t	type_index_ {0}
	Type index(tag) that indicates the type of the object. More...
RefCounterType	ref_counter_ {0}
	The internal reference counter. More...
FDeleter	deleter_ = nullptr
	deleter of this object to enable customized allocation. If the deleter is nullptr, no deletion will be performed. The creator of the object must always set the deleter field properly. More...

Friends
template<typename >
class	ObjAllocatorBase
template<typename >
class	ObjectPtr
	we always used ObjectPtr for a reference pointer to the node, so this alias can be changed in case. More...
class	MXNetRetValue
class	ObjectInternal

Detailed Description

base class of all object containers.

Sub-class of objects should declare the following static constexpr fields:

• _type_index: Static type index of the object, if assigned to TypeIndex::kDynamic the type index will be assigned during runtime. Runtime type index can be accessed by ObjectType::TypeIndex();
• _type_key: The unique string identifier of tyep type.
• _type_final: Whether the type is terminal type(there is no subclass of the type in the object system). This field is automatically set by marco MXNET_DECLARE_FINAL_OBJECT_INFO It is still OK to sub-class a terminal object type T and construct it using make_object. But IsInstance check will only show that the object type is T(instead of the sub-class).

The following two fields are necessary for base classes that can be sub-classed.

• _type_child_slots: Number of reserved type index slots for child classes. Used for runtime optimization for type checking in IsInstance. If an object's type_index is within range of [type_index, type_index + _type_child_slots] Then the object can be quickly decided as sub-class of the current object class. If not, a fallback mechanism is used to check the global type table. Recommendation: set to estimate number of children needed.
• _type_child_slots_can_overflow: Whether we can add additional child classes even if the number of child classes exceeds the _type_child_slots. A fallback mechanism to check global type table will be used. Recommendation: set to false for optimal runtime speed if we know exact number of children.

Two macros are used to declare helper functions in the object:

• Use MXNET_DECLARE_BASE_OBJECT_INFO for object classes that can be sub-classed.
• Use MXNET_DECLARE_FINAL_OBJECT_INFO for object classes that cannot be sub-classed.

New objects can be created using make_object function. Which will automatically populate the type_index and deleter of the object.

See also

make_object

ObjectPtr

ObjectRef

// Create a base object
class BaseObj : public Object {
 public:
  // object fields
  int field0;

  // object properties
  static constexpr const uint32_t _type_index = TypeIndex::kDynamic;
  static constexpr const char* _type_key = "test.BaseObj";
  MXNET_DECLARE_BASE_OBJECT_INFO(BaseObj, Object);
};

class ObjLeaf : public ObjBase {
 public:
  // fields
  int child_field0;
  // object properties
  static constexpr const uint32_t _type_index = TypeIndex::kDynamic;
  static constexpr const char* _type_key = "test.LeafObj";
  MXNET_DECLARE_BASE_OBJECT_INFO(LeaffObj, Object);
};

// The following code should be put into a cc file.
MXNET_REGISTER_OBJECT_TYPE(ObjBase);
MXNET_REGISTER_OBJECT_TYPE(ObjLeaf);

// Usage example.
void TestObjects() {
  // create an object
  ObjectRef leaf_ref(make_object<LeafObj>());
  // cast to a specific instance
  const LeafObj* leaf_ptr = leaf_ref.as<LeafObj>();
  CHECK(leaf_ptr != nullptr);
  // can also cast to the base class.
  CHECK(leaf_ref.as<BaseObj>() != nullptr);
}

Member Typedef Documentation

typedef void(* mxnet::runtime::Object::FDeleter) (Object *self)

Object deleter.

Parameters

self	pointer to the Object.

using mxnet::runtime::Object::RefCounterType = std::atomic<int32_t>

Constructor & Destructor Documentation

mxnet::runtime::Object::Object ( )

inline

mxnet::runtime::Object::Object ( const Object &  other )

inline

mxnet::runtime::Object::Object ( Object &&  other )

inline

Member Function Documentation

static uint32_t mxnet::runtime::Object::_GetOrAllocRuntimeTypeIndex ( )

inlinestatic

void mxnet::runtime::Object::DecRef ( )

inlineprotected

developer function, decrease reference counter.

Note

The deleter will be called when ref_counter_ becomes zero.

static MXNET_DLL uint32_t mxnet::runtime::Object::GetOrAllocRuntimeTypeIndex ( const std::string &  key, uint32_t  static_tindex, uint32_t  parent_tindex, uint32_t  type_child_slots, bool  type_child_slots_can_overflow  )

staticprotected

Get the type index using type key.

When the function is first time called for a type, it will register the type to the type table in the runtime. If the static_tindex is TypeIndex::kDynamic, the function will allocate a runtime type index. Otherwise, we will populate the type table and return the static index.

Parameters

key	the type key.
static_tindex	The current _type_index field. can be TypeIndex::kDynamic.
parent_tindex	The index of the parent.
type_child_slots	Number of slots reserved for its children.
type_child_slots_can_overflow	Whether to allow child to overflow the slots.

Returns

The allocated type index.

std::string mxnet::runtime::Object::GetTypeKey ( ) const

inline

Returns

the type key of the object.

Note

this operation is expensive, can be used for error reporting.

size_t mxnet::runtime::Object::GetTypeKeyHash ( ) const

inline

Returns

A hash value of the return of GetTypeKey.

void mxnet::runtime::Object::IncRef ( )

inlineprotected

developer function, increases reference counter.

template<typename TargetType >

bool mxnet::runtime::Object::IsInstance ( ) const

inline

Check if the object is an instance of TargetType.

Template Parameters

TargetType

The target type to be checked.

Returns

Whether the target type is true.

Object& mxnet::runtime::Object::operator= ( const Object &  other )

inline

Object& mxnet::runtime::Object::operator= ( Object &&  other )

inline

static uint32_t mxnet::runtime::Object::RuntimeTypeIndex ( )

inlinestatic

uint32_t mxnet::runtime::Object::type_index ( ) const

inline

Returns

The internal runtime type index of the object.

static MXNET_DLL std::string mxnet::runtime::Object::TypeIndex2Key ( uint32_t  tindex )

static

Get the type key of the corresponding index from runtime.

Parameters

tindex

The type index.

Returns

the result.

static MXNET_DLL size_t mxnet::runtime::Object::TypeIndex2KeyHash ( uint32_t  tindex )

static

Get the type key hash of the corresponding index from runtime.

Parameters

tindex

The type index.

Returns

the related key-hash.

static MXNET_DLL uint32_t mxnet::runtime::Object::TypeKey2Index ( const std::string &  key )

static

Get the type index of the corresponding key from runtime.

Parameters

key	The type key.

Returns

the result.

Friends And Related Function Documentation

friend class MXNetRetValue

friend

template<typename >

friend class ObjAllocatorBase

friend

friend class ObjectInternal

friend

template<typename >

friend class ObjectPtr

friend

we always used ObjectPtr for a reference pointer to the node, so this alias can be changed in case.

By default, ObjectPtr is a std::shared_ptr of node

Member Data Documentation

constexpr uint32_t mxnet::runtime::Object::_type_child_slots = 0

static

constexpr bool mxnet::runtime::Object::_type_child_slots_can_overflow = true

static

constexpr bool mxnet::runtime::Object::_type_final = false

static

constexpr uint32_t mxnet::runtime::Object::_type_index = TypeIndex::kDynamic

static

constexpr const char* mxnet::runtime::Object::_type_key = "Object"

static

FDeleter mxnet::runtime::Object::deleter_ = nullptr

protected

deleter of this object to enable customized allocation. If the deleter is nullptr, no deletion will be performed. The creator of the object must always set the deleter field properly.

RefCounterType mxnet::runtime::Object::ref_counter_ {0}

protected

The internal reference counter.

uint32_t mxnet::runtime::Object::type_index_ {0}

protected

Type index(tag) that indicates the type of the object.

---

The documentation for this class was generated from the following file:

• /work/mxnet/include/mxnet/runtime/object.h