omni::core::ImplementsWeak

template<typename T, typename ...Rest> struct ImplementsWeak : public omni::core::ImplementsCast<T, Rest...>

Helper template for implementing one or more interfaces that support weak pointers.

This class has similar functionality as Implements but adds support for IWeakObject.

As an example, consider the following interface:

// an interface that supports weak pointers should inherit from IWeakObject rather than IObject
class IWeakExample_abi : public Inherits<IWeakObject, OMNI_TYPE_ID("carb.tests.IWeakExample")>
{
protected:
    // interfaces that support weak pointers can have methods just like any other interface...
    virtual uint32_t doFoo_abi() noexcept = 0;
    virtual bool doBar_abi() noexcept = 0;
};

Note that the interface inherits from IWeakObject rather than IObject.

To implement the interface above, ImplementsWeak (i.e. this class) can be used as follows:

// when implementing an interface that supports weak pointers, use ImplementsWeak rather than Implements
class WeakExample : public ImplementsWeak<IWeakExample>
{
public:
    static ObjectPtr<WeakExample> create() noexcept;

    virtual ~WeakExample() noexcept;

protected:
    WeakExample() noexcept;

    virtual uint32_t doFoo_abi() noexcept override;

    virtual bool doBar_abi() noexcept override;
};

Public Functions

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline ObjectPtr<IWeakObjectControlBlock> getWeakObjectControlBlock() noexcept

Returns a control block containing reference count information needed for the implementation of weak pointers.

Users of weak pointers must never call this method. Rather, they should focus on exclusively using WeakPtr.

Implementers of this method are encouraged to use the implementation found in omni::core::ImplementsWeak.

The returns pointer is never nullptr.

The returned pointer will have IObject::acquire() called on it before being returned.

Thread Safety: This method is thread safe.

inline void *cast(omni::core::TypeId id) noexcept: See omni::core::IObject::cast.

Protected Functions

inline virtual ~ImplementsWeak() noexcept: Destructor.

inline virtual void acquire_abi() noexcept override

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline virtual void release_abi() noexcept override

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety: This method is thread safe.

inline virtual IWeakObjectControlBlock *getWeakObjectControlBlock_abi() noexcept override

Returns a control block containing reference count information needed for the implementation of weak pointers.

Users of weak pointers must never call this method. Rather, they should focus on exclusively using WeakPtr.

Implementers of this method are encouraged to use the implementation found in omni::core::ImplementsWeak.

The returns pointer is never nullptr.

The returned pointer will have IObject::acquire() called on it before being returned.

Thread Safety: This method is thread safe.

inline virtual void *cast_abi(TypeId id) noexcept override

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety: This method is thread safe.