nx_metadata_sdk 1.0 Metadata SDK

Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | List of all members
nx::sdk::IRefCountable Class Referenceabstract

`#include <i_ref_countable.h>`

Inheritance diagram for nx::sdk::IRefCountable:

## Classes
struct | InterfaceId

## Public Member Functions
virtual | ~IRefCountable ()=default
template<class Interface >
Ptr< Interface > | queryInterface ()
template<class Interface >
Ptr< const Interface > | queryInterface () const
virtual int | addRef () const =0
virtual int | releaseRef () const =0
int | refCountThreadUnsafe () const

## Static Public Member Functions
static auto | interfaceId ()

## Protected Member Functions
virtual IRefCountable * | queryInterface (const InterfaceId *id)

## Static Protected Member Functions
template<int len>
static const InterfaceId * | makeId (const char(&charArray)[len])
template<int len, int alternativeLen>
static std::vector< const InterfaceId * > | makeIdWithAlternative (const char(&charArray)[len], const char(&alternativeCharArray)[alternativeLen])
template<class TemplateInstance , class TemplateArg , int len>
static const InterfaceId * | makeIdForTemplate (const char(&baseIdCharArray)[len])
static std::vector< const InterfaceId * > | alternativeInterfaceIds (const InterfaceId *id)
static std::vector< const InterfaceId * > | alternativeInterfaceIds (std::vector< const InterfaceId *> ids)

## Detailed Description

Base for all interfaces - abstract classes with only pure-virtual non-overloaded functions, so that an object implementing an interface can be passed by pointer between dynamic libraries compiled using potentially different compilers and their standard libraries. Such abstraction is needed to enable plugins. It is somewhat similar to Microsoft Component Object Model (COM).

Interface methods are allowed to use only C-style input and output types (without STL classes), because on each side of a dynamic library different implementations/versions of STL can be used. The only ABI aspects that interfaces rely upon - size of pointer, and order of methods in a VMT (in the order of declaration, base class methods first). Overloaded methods are not allowed because their order in VMS can be different across compilers. Also dynamic_cast can not be used for such objects, because data structures behind the VMT can be different across compilers.

Interfaces may contain type definitions and non-virtual inline utility methods (they will be compiled by each side independently).

Each object implementing an interface should have an internal reference counter, which, when decremented to zero, triggers object deletion.

To provide dynamic-cast-like behavior, and more generally, the ability to yield objects implementing other interfaces (not necessarily the same object as the one being queried), each object must implement queryInterface() which takes an interface identifier and returns a pointer to the object implementing the requested interface.

General rules for passing objects with reference counting:

- If a function returns a pointer to an interface, it should increment the counter prior to returning, thus, the counter should be decremented by the caller after using the object.
- If a function receives a pointer to an interface as an argument, it should not decrement its counter, and should not increment it (unless it needs the object to survive this call).
- If a class owns an object in a field, it should decrement its counter in the destructor.

NOTE: For binary compatibility with old plugins, the VMT layout of this interface (4 entries - destructor, queryInterface(), addRef(), releaseRef()) should not change, as well as the binary prototypes (arguments and return values) of its entries.

## Constructor & Destructor Documentation

## ◆ ~IRefCountable()

virtual nx::sdk::IRefCountable::~IRefCountable | ( |  | ) |
| virtual default

VMT #0.

## Member Function Documentation

## ◆ addRef()

virtual int nx::sdk::IRefCountable::addRef | ( |  | ) | const
| pure virtual

VMT #2.

Returns
  New reference count.

## ◆ interfaceId()

static auto nx::sdk::IRefCountable::interfaceId | ( |  | ) |
| inline static

Each derived interface is expected to implement such static method with its own data.

## ◆ makeId()

template<int len>

static const InterfaceId* nx::sdk::IRefCountable::makeId | ( | const char(&) | charArray[len] | ) |
| inline static protected

Intended to be used in interfaceId(). Can be called only with a string literal.

## ◆ makeIdForTemplate()

template<class TemplateInstance , class TemplateArg , int len>

static const InterfaceId* nx::sdk::IRefCountable::makeIdForTemplate | ( | const char(&) | baseIdCharArray[len] | ) |
| inline static protected

Makes a compound interface id for interface templates like IList<IItem>. Usage:

static auto interfaceId()
{
return IList::template makeIdForTemplate<IList<IItem>, IItem>("nx::sdk::IList");
}

NOTE: Currently, this function does not support interfaces with alternative interface ids.

## ◆ makeIdWithAlternative()

template<int len, int alternativeLen>

static std::vector<const InterfaceId*> nx::sdk::IRefCountable::makeIdWithAlternative | ( | const char(&) | charArray[len],
|  | const char(&) | alternativeCharArray[alternativeLen]
| ) |  |
| inline static protected

Intended to be used in interfaceId(). Can be called only with two string literals.

## ◆ queryInterface()

virtual IRefCountable* nx::sdk::IRefCountable::queryInterface | ( | const InterfaceId * | id | ) |
| inline protected virtual

VMT #1.

Intended to be called indirectly, via queryInterface<Interface>(), hence `protected`.

Returns
  Object that requires releaseRef() by the caller when it no longer needs it, or null if the requested interface is not implemented.

Reimplemented in nx::sdk::ref_countable_ut::NewInterface.

## ◆ refCountThreadUnsafe()

int nx::sdk::IRefCountable::refCountThreadUnsafe | ( |  | ) | const
| inline

Intended for debug. Is not thread-safe, because does addRef()/releaseRef() pair of calls.

Returns
  Reference counter, or 0 if the pointer is null.

## ◆ releaseRef()

virtual int nx::sdk::IRefCountable::releaseRef | ( |  | ) | const
| pure virtual

VMT #3.

Returns
  New reference count, having deleted the object if it reaches zero.

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

- src/nx/sdk/i_ref_countable.h