omni::core::IWeakObjectControlBlock

class IWeakObjectControlBlock : public omni::core::Generated<omni::core::IWeakObjectControlBlock_abi>

Control block to maintain weak and strong reference counts for an object.

The IWeakObject interface supports the notion of “weak pointers”. Unlike “strong pointers” (e.g. ObjectPtr) weak pointers do not affect the pointee’s reference count. While this sounds like a raw pointer (and possibly a bad idea), the magic of a weak pointer is that if the pointee’s reference count goes to zero, the weak pointer updates its internal pointer to nullptr.

IWeakObjectControlBlock is an ABI-safe object used to store a pointer to both the object and the object’s reference count (i.e. the “strong count”). This object additionally stores a “weak count”, which is a count of objects pointing to the IWeakObjectControlBlock.

Both WeakPtr and IWeakObject affect the “weak count”.

Only ObjectPtr will affect the “strong count”.

Direct usage of this object should be avoided. See WeakPtr to learn how weak pointers are used in practice.

Advanced: Design Considerations

The design of ONI’s weak pointers takes three main design considerations into account:

The user API should work similar to std::weak_ptr.
Enabling weak pointer support for an object should should not tank performance in hot code paths.
Weak pointers must be able to point to object’s whose DLL has been unloaded from memory.

Above, the final point has a strong affect on the implementation of weak pointers. In particular, this object (i.e. IWeakObjectControlBlock). Consider:

For a virtual function to be called successfully, the code implementing the virtual function must still be loaded.
An IWeakObjectControlBlock may outlive the DLL that created the object to which it points.

Rather than exposing a raw struct with the weak and strong counts (and associated inline code to manipulate them), this interface is used to hide both the counts and the manipulation logic. However, this introduces virtual functions, which could potentially be unloaded. To address the unloading problem, carb.dll provides omni::core::getOrCreateWeakObjectControlBlock(). This C-ABI returns an implementation of IWeakObjectControlBlock implemented within carb.dll. This effectively avoids the DLL unloading problem, since carb.dll is considered a core dependency that cannot be unloaded and therefore the virtual function implementations for IWeakObjectControlBlock will always be loaded.

Public Functions

inline omni::core::ObjectPtr<omni::core::IObject> getObject() noexcept

Returns a pointer to the object pointed to by this control block. May return nullptr.

If the object pointed to by this control block has a strong reference count of zero, nullptr is returned. Otherwise, IObject::acquire() is called on the object before being returned.

Thread Safety: This method is thread safe.

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

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.

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.

Protected Functions

virtual IObject *getObject_abi() noexcept = 0

Returns a pointer to the object pointed to by this control block. May return nullptr.

If the object pointed to by this control block has a strong reference count of zero, nullptr is returned. Otherwise, IObject::acquire() is called on the object before being returned.

Thread Safety: This method is thread safe.

virtual void *cast_abi(TypeId id) noexcept = 0

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.

virtual void acquire_abi() noexcept = 0

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.

virtual void release_abi() noexcept = 0

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.