Diligent::IReferenceCounters Class Reference

#include <ReferenceCounters.h>

Public Member Functions
virtual ReferenceCounterValueType	AddStrongRef ()=0
	Increments the number of strong references by 1.
virtual ReferenceCounterValueType	ReleaseStrongRef ()=0
virtual ReferenceCounterValueType	AddWeakRef ()=0
	Increments the number of weak references by 1.
virtual ReferenceCounterValueType	ReleaseWeakRef ()=0
virtual void	QueryObject (struct IObject **ppObject)=0
	Queries a pointer to the IUnknown interface of the referenced object.
virtual ReferenceCounterValueType	GetNumStrongRefs () const =0
	Returns the number of outstanding strong references.
virtual ReferenceCounterValueType	GetNumWeakRefs () const =0
	Returns the number of outstanding weak references.

Detailed Description

Base interface for a reference counter object that stores the number of strong and weak references and the pointer to the object. It is necessary to separate reference counters from the object to support weak pointers.

Member Function Documentation

AddStrongRef()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::AddStrongRef ( )

pure virtual

Increments the number of strong references by 1.

Returns

The number of strong references after incrementing the counter.

Remarks

The counter update is thread-safe, but the caller must already own a strong reference or otherwise externally guarantee object lifetime. AddStrongRef() must not be used to promote a weak reference because another thread may be releasing the final strong reference at the same time. Use QueryObject() or RefCntWeakPtr::Lock() for weak-to-strong promotion.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter.

AddWeakRef()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::AddWeakRef ( )

pure virtual

Increments the number of weak references by 1.

Returns

The number of weak references after incrementing the counter.

Remarks

The counter update is thread-safe, but the caller must already own a strong reference, own a weak reference, or otherwise externally guarantee that the reference counters object is still alive.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter.

GetNumStrongRefs()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::GetNumStrongRefs ( ) const

pure virtual

Returns the number of outstanding strong references.

Returns

The number of strong references.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter. The only reliable value is 0 as the object is destroyed when the last strong reference is released.

GetNumWeakRefs()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::GetNumWeakRefs ( ) const

pure virtual

Returns the number of outstanding weak references.

Returns

The number of weak references.

Remarks

Diligent's RefCountedObject implementation keeps one implicit weak reference while the referenced object is alive. The returned value includes this implicit weak reference, so one external weak pointer to a live object is reported as two weak references.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter.

QueryObject()

virtual void Diligent::IReferenceCounters::QueryObject ( struct IObject ** ppObject )

pure virtual

Queries a pointer to the IUnknown interface of the referenced object.

Parameters

[out]

ppObject

- Memory address where the pointer to the object will be stored.

Remarks

If the object was destroyed, nullptr will be written to *ppObject. If the object was not released, the pointer to the object's IUnknown interface will be stored. In this case, the number of strong references to the object will be incremented by 1.
This method is a safe way to promote a weak reference to a strong reference. Direct AddStrongRef() on a raw pointer does not provide the required lifetime synchronization.
The method is thread-safe and does not require explicit synchronization.

ReleaseStrongRef()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::ReleaseStrongRef ( )

pure virtual

Decrements the number of strong references by 1 and destroys the referenced object when the counter reaches zero. If there are no more weak references, destroys the reference counters object itself.

Returns

The number of strong references after decrementing the counter.

Remarks

The referenced object is destroyed when the last strong reference is released. RefCountedObject keeps an implicit weak reference while the object is alive, so the reference counters object remains alive until after the object destructor returns.
If there are no more weak references after that, the reference counters object itself is also destroyed.
The method is thread-safe and does not require explicit synchronization.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter. The only reliable value is 0 as the object is destroyed when the last strong reference is released.

ReleaseWeakRef()

virtual ReferenceCounterValueType Diligent::IReferenceCounters::ReleaseWeakRef ( )

pure virtual

Decrements the number of weak references by 1. If there are no more strong and weak references, destroys the reference counters object itself.

Returns

The number of weak references after decrementing the counter.

Remarks

The method is thread-safe and does not require explicit synchronization.

Note

In a multithreaded environment, the returned number may not be reliable as other threads may simultaneously change the actual value of the counter.