ClassInterface Class Reference

#include <objectbase.h>

Detailed Description

A ClassInterface object represents an object class at runtime, see vinterfaces. Such an object class can be published by MAXON_DECLARATION, and it is then typically defined by MAXON_COMPONENT_CLASS_REGISTER.

A class consists of several components (see ComponentDescriptor), each of which may implement several virtual interfaces (declared by MAXON_INTERFACE). The class itself then implements all interfaces of all of its components. Information about components and interfaces can be obtained from the ClassInfo object returned by GetClassInfo().

After allocation of a class, you have to add the components of which it shall consist via AddComponent() or AddComponents(). Afterwards, you can invoke Finalize() to make the class ready for use. From then on, only const methods may be invoked on a class. If you use GenericClass or Class to access a class, this is automatically guaranteed as those are const references. If you don't invoke Finalize(), this will be done implicitly when the first instance of the class is allocated.

The MAXON_COMPONENT_CLASS_REGISTER and MAXON_COMPONENT_OBJECT_REGISTER macros greatly simplify the setup of a class.

ClassInterface objects are automatically registered at the Classes registry, so with

Class<MyType> cls = Classes::Get<MyType>("com.foo.class.bar");
PyObject * cls
Definition: abstract.h:365

you can look for the class with identifier "com.foo.class.bar". MyType is the expected reference type of instances of the class.

Public Types

enum class  KIND {
  NORMAL ,
  SINGLETON ,
  ABSTRACT
}
 

Public Member Functions

enum maxon::ClassInterface::KIND MAXON_ENUM_LIST_CLASS (KIND)
 
MAXON_METHOD const IdGetId () const
 
MAXON_METHOD KIND GetKind () const
 
MAXON_METHOD Int GetSize () const
 
MAXON_METHOD Block< const ComponentInfo *const > GetComponents () const
 
MAXON_METHOD Result< void > AddComponent (const ComponentDescriptor &component)
 
MAXON_METHOD void RemoveLastComponent ()
 
MAXON_METHOD Result< void > AddComponents (const Class<> &cls)
 
MAXON_METHOD Result< void > Finalize ()
 
MAXON_METHOD Bool IsFinalized () const
 
MAXON_METHOD const Block< const InterfaceReference *const > & GetImplementedInterfaces () const
 
MAXON_METHOD const DataTypeGetDataType () const
 
MAXON_METHOD Result< typename maxon::details::ClassGetNonConst< REF >::typeCreate () const
 
MAXON_METHOD Result< ObjectInterface * > CreatePointer (Int size=-1) const
 
MAXON_FUNCTION Bool Implements (const InterfaceReference &iref) const
 
template<typename I >
MAXON_FUNCTION Bool Implements () const
 
MAXON_METHOD Bool IsSubclassOf (const Class<> &other) const
 
MAXON_METHOD String ToString (const FormatStatement *formatStatement=nullptr) const
 
MAXON_METHOD const DataDictionary & GetMetaData () const
 
MAXON_METHOD void InitMetaData (DataDictionary &&data)
 
void PrivateInitMetaData (ResultOk< void > &&data)
 
template<typename T >
void PrivateInitMetaData (Result< T > &&data)
 

Static Public Member Functions

static MAXON_METHOD ClassInterfaceAlloc (MAXON_SOURCE_LOCATION_DECLARATION, const Id &cid, KIND kind=KIND::NORMAL)
 
static MAXON_METHOD void DeleteInstance (const ObjectInterface *object)
 
static MAXON_METHOD void DestructInstance (const ObjectInterface *object)
 

Protected Member Functions

MAXON_METHOD const ClassInfo * GetInfo () const
 
MAXON_METHOD Result< IntAddProxyComponent (const ComponentDescriptor &component, Bool shared)
 

Static Protected Member Functions

static MAXON_METHOD Result< void > CopyInstance (ObjectInterface *dest, const ObjectInterface *src)
 
static MAXON_METHOD void * GetOrCreateMTable (ClassInfo *info, const InterfaceReference &i)
 
static const InterfaceInfo * GetValidInterfaceInfo (const ClassInfo *info, Int offset)
 

Private Member Functions

 MAXON_INTERFACE_NONVIRTUAL (ClassInterface, MAXON_REFERENCE_CONST, "net.maxon.interface.class")
 
 MAXON_GENERIC ((Out) typename REF=ObjectRef)
 

Friends

class ObjectInterface
 
class ObjectModel
 
class ComponentDescriptor
 
class reflection::ProxyImpl
 
template<typename , typename , Bool >
struct CombinedMTableBase
 
template<typename , typename , typename , typename... >
class ComponentWithBase
 

Member Enumeration Documentation

◆ KIND

enum KIND
strong

An object class is of one of the kinds defined by this enum.

Enumerator
NORMAL 

A normal object class.

SINGLETON 

A singleton object class, i.e., a class with exactly one instance. The instance can be obtained with Create().

ABSTRACT 

An abstract object class. Create() will return an UnsupportedOperationError.

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( ClassInterface  ,
MAXON_REFERENCE_CONST  ,
"net.maxon.interface.class"   
)
private

◆ MAXON_GENERIC()

MAXON_GENERIC ( (Out) typename  REF = ObjectRef)
private

◆ MAXON_ENUM_LIST_CLASS()

enum maxon::ClassInterface::KIND MAXON_ENUM_LIST_CLASS ( KIND  )

◆ Alloc()

static MAXON_METHOD ClassInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  ,
const Id cid,
KIND  kind = KIND::NORMAL 
)
static

Allocates a new ClassInterface object with a given identifier. The new class doesn't contain any components, you have to add them afterwards by AddComponent() or AddComponents(), and to finally invoke Finalize to complete the class.

Parameters
[in]allocLocationPass MAXON_SOURCE_LOCATION(_NAME) to add the current source line and file.
[in]cidUnique identifier for the class.
[in]kindUse KIND::SINGLETON for a singleton class or KIND::ABSTRACT for an abstract class.
Returns
Pointer to a new ClassInterface object.

◆ GetId()

MAXON_METHOD const Id& GetId ( ) const

Returns the identifier of this object class. Class identifiers are unique and should follow the naming convention of the MAXON API:

  • It starts with reverse domain name notation of an internet domain you own (such as net.maxon in the case of MAXON).
  • Then it can have a part which narrows down the area to which the class belongs (such as image or node). In the case of MAXON-provided classes this part often relates to the module in which the classes are implemented.
  • Then there's class followed by a local name of the class. Examples for complete ids are net.maxon.class.hierarchyobject, net.maxon.image.class.mediaoutputtexture or net.maxon.node.class.nodesystem.
    Returns
    Class identifier.

◆ GetKind()

MAXON_METHOD KIND GetKind ( ) const

Returns the kind of this object class, see KIND.

Returns
Kind of this object class.

◆ GetSize()

MAXON_METHOD Int GetSize ( ) const

Returns the size in bytes of an instance of this class.

Returns
Byte size of an instance of this class.

◆ GetComponents()

MAXON_METHOD Block<const ComponentInfo* const> GetComponents ( ) const

Returns a list of all class components. The components are in order of registration.

Returns
Reference to the list of components.

◆ AddComponent()

MAXON_METHOD Result<void> AddComponent ( const ComponentDescriptor component)

Adds a component to this class. The class must not yet have been finalized (by invocation of Finalize()). The added component will overwrite the vtables of the interfaces it implements (see InterfaceInfo), but the previous values are stored (in the _supervtable member of ComponentInfo) and used by the Super function of the component implementation.

Parameters
[in]componentComponent to add.
Returns
OK on success. In the case of an error, the class hasn't been changed.
See also
AddComponents

◆ RemoveLastComponent()

MAXON_METHOD void RemoveLastComponent ( )

@MAXON_ANNOTATION{refclass=false}

◆ AddComponents()

MAXON_METHOD Result<void> AddComponents ( const Class<> &  cls)

Adds all components of class cls to this class. This class must not yet have been finalized (by invocation of Finalize()). The addition is done in the same order as for the original class. Afterwards, cls can be seen as a base class of this class.

Parameters
[in]clsImplementation class of the component to add.
Returns
OK on success. In the case of an error, the class shouldn't be used.
See also
AddComponent

◆ Finalize()

MAXON_METHOD Result<void> Finalize ( )

Finalizes this class so that it can be used afterwards. The class has to be built before by AddComponent(). Some internal data will be set-up for the class so that it is ready for use. If you don't invoke Finalize(), it will be done implicitly when an object of the class is instantiated for the first time.

Returns
OK on success. If an error occurred, the class shouldn't be used.
See also
AddComponent

◆ IsFinalized()

MAXON_METHOD Bool IsFinalized ( ) const

Returns true if the class has been finalized successfully before.

Returns
True if the class is finalized.
See also
Finalize

◆ GetImplementedInterfaces()

MAXON_METHOD const Block<const InterfaceReference* const>& GetImplementedInterfaces ( ) const

Returns a block of all interfaces which this class implements. For each interface, the block will also contain its base interfaces. The interfaces will be sorted according to their depth and, at second level, to their ids.

Returns
Block of all implemented interfaces.

◆ GetDataType()

MAXON_METHOD const DataType& GetDataType ( ) const

Returns the data type corresponding to the set of implemented interfaces of this class. For an abstract class this will return nullptr.

Returns
Data type of this class.

◆ Create()

MAXON_METHOD Result<typename maxon::details::ClassGetNonConst<REF>::type> Create ( ) const

Constructs a new instance of this class. This will invoke the constructors of each component in the order of addition, and then the InitComponent functions of each component. When one of the InitComponent functions fails with an error, FreeComponent will be invoked on the previous (already initialized) components, the component destructors will be invoked, the memory will by freed, and Create() returns the error.

For a singleton class, this doesn't create a new instance, but returns the singleton instance of this class. This instance is automatically created on finalization of the class.

For an abstract class, this will always return an UnsupportedOperationError.

Returns
Reference to new instance, or an error if the allocation or initialization failed.

◆ CreatePointer()

MAXON_METHOD Result<ObjectInterface*> CreatePointer ( Int  size = -1) const

Constructs a new instance of this class. This will invoke the constructors of each component in the order of addition, and then the InitComponent functions of each component. When one of the InitComponent functions fails with an error, FreeComponent will be invoked on the previous (already initialized) components, the component destructors will be invoked, the memory will by freed, and CreatePointer() returns the error.

For an abstract class, this will always return an UnsupportedOperationError.

The reference counter of the returned object will be zero.

Parameters
[in]sizeOptional memory size for the allocation. This can be used if the object needs some extra space.
Returns
Pointer to the new instance, or an error if the allocation or initialization failed.
Warning
This function must not be used for a singleton class, use Create() instead.

@MAXON_ANNOTATION{refclass=false}

◆ Implements() [1/2]

MAXON_FUNCTION Bool Implements ( const InterfaceReference &  iref) const

Checks if the class implements the interface iref. This means that this class contains a component implementing the interface.

Parameters
[in]irefAn interface.
Returns
True if this class implements the interface, false otherwise.

◆ Implements() [2/2]

MAXON_FUNCTION Bool Implements ( ) const

Checks if the class implements the interface I. This means that this class contains a component implementing the interface.

Template Parameters
IAn interface.
Returns
True if this class implements the interface I, false otherwise.

◆ IsSubclassOf()

MAXON_METHOD Bool IsSubclassOf ( const Class<> &  other) const

Checks if this class is a subclass of other, i.e., if this class has all components of other.

Parameters
[in]otherAnother class.
Returns
True if this class is a subclass of other, false otherwise.

◆ ToString()

MAXON_METHOD String ToString ( const FormatStatement formatStatement = nullptr) const

Returns a readable string of the content.

Parameters
[in]formatStatementNullptr or additional formatting instruction. Currently no additional formatting instructions are supported.
Returns
The converted result. The representation consists of the class identifier prefixed by "class ".

◆ GetMetaData()

MAXON_METHOD const DataDictionary& GetMetaData ( ) const

Returns the meta data of this class. Usually that's a null reference, but one can set up the meta data either by InitMetaData() or by adding a function CreateClassMetaData() to the component which is used to setup a class:

class MyComponent : public Component<MyComponent, MyInterface>
{
public:
...
static Result<DataDictionary> CreateClassMetaData()
{
DataDictionary dict;
... // setup dict
return dict;
}
};
MAXON_COMPONENT_CLASS_REGISTER(MyComponent, "net.maxon.class.myclass");
PyObject PyObject * dict
Definition: abstract.h:150
ComponentWithBase< C, ComponentRoot, INTERFACES... > Component
Definition: objectbase.h:2794
#define MAXON_COMPONENT(KIND,...)
Definition: objectbase.h:2212
#define MAXON_COMPONENT_CLASS_REGISTER(C,...)
Definition: objectbase.h:2409
#define iferr_scope
Definition: resultbase.h:1374
Returns
The meta data of this class.

◆ InitMetaData()

MAXON_METHOD void InitMetaData ( DataDictionary &&  data)

Initializes the meta data (to be returned by GetMetaData()) for this class. You can also setup the meta data by a function CreateClassMetaData() in a component, see GetMetaData().

Parameters
[in]dataThe meta data.

◆ PrivateInitMetaData() [1/2]

void PrivateInitMetaData ( ResultOk< void > &&  data)

◆ PrivateInitMetaData() [2/2]

void PrivateInitMetaData ( Result< T > &&  data)

◆ DeleteInstance()

static MAXON_METHOD void DeleteInstance ( const ObjectInterface object)
static

Deletes an instance of a class. This is automatically invoked if the reference count of the instance reaches zero.

Parameters
[in]objectInstance to delete, must not be nullptr.

◆ DestructInstance()

static MAXON_METHOD void DestructInstance ( const ObjectInterface object)
static

Destructs an instance of a class. This is automatically invoked if the reference count of the instance reaches zero.

Parameters
[in]objectInstance to destruct, must not be nullptr.

◆ CopyInstance()

static MAXON_METHOD Result<void> CopyInstance ( ObjectInterface dest,
const ObjectInterface src 
)
staticprotected

Copies the component data of objects. This is invoked by ObjectInterface::CopyFrom.

Parameters
[out]destDestination object, may be nullptr.
[in]srcSource object, may be nullptr.
Returns
OK on success. This will report a NullptrError if any of the arguments is nullptr.

◆ GetInfo()

MAXON_METHOD const ClassInfo* GetInfo ( ) const
protected

Returns the ClassInfo object of this class. This is only needed internally.

Returns
ClassInfo object of this class. Will never be nullptr.

◆ GetOrCreateMTable()

static MAXON_METHOD void* GetOrCreateMTable ( ClassInfo *  info,
const InterfaceReference &  i 
)
staticprotected

Returns a pointer to the MTable for the interface having the specified offset. The memory for the MTable is allocated if necessary.

Parameters
[in]infoClassInfo object.
[in]iThe interface for which the method table shall be obtained.
Returns
Pointer to the MTable of the interface, or nullptr if the MTable allocation failed.

◆ GetValidInterfaceInfo()

static const InterfaceInfo* GetValidInterfaceInfo ( const ClassInfo *  info,
Int  offset 
)
staticprotected

Returns the InterfaceInfo for the interface having the specified offset.

Parameters
[in]infoClassInfo object of the class in question.
[in]offsetOffset of the interface within the interface table.
Returns
InterfaceInfo object, or nullptr if the class doesn't implement the interface.

◆ AddProxyComponent()

MAXON_METHOD Result<Int> AddProxyComponent ( const ComponentDescriptor component,
Bool  shared 
)
protected

Friends And Related Function Documentation

◆ ObjectInterface

friend class ObjectInterface
friend

◆ ObjectModel

friend class ObjectModel
friend

◆ ComponentDescriptor

friend class ComponentDescriptor
friend

◆ reflection::ProxyImpl

friend class reflection::ProxyImpl
friend

◆ CombinedMTableBase

friend struct CombinedMTableBase
friend

◆ ComponentWithBase

friend class ComponentWithBase
friend