Diligent Engine API Reference: Diligent::StateObjectsRegistry< ResourceDescType > Class Template Reference

Diligent Engine API Reference

Public Member Functions | Static Public Attributes | List of all members
Diligent::StateObjectsRegistry< ResourceDescType > Class Template Reference

Template class implementing state object registry. More...

## Public Member Functions
void | Add (const ResourceDescType &ObjectDesc, IDeviceObject *pObject)
| Adds a new object to the registry. More...
void | Find (const ResourceDescType &Desc, IDeviceObject **ppObject)
| Finds the object in the registry.
void | Purge ()
| Purges outstanding deleted objects from the registry.
void | ReportDeletedObject ()
| Increments the number of outstanding deleted objects. When this number reaches DeletedObjectsToPurge, Purge() will be called.

## Static Public Attributes
static constexpr int | DeletedObjectsToPurge = 32
| Number of outstanding deleted objects to purge the registry.

## Detailed Description

### template<typename ResourceDescType>
class Diligent::StateObjectsRegistry< ResourceDescType >

Template class implementing state object registry.

Template Parameters

  ResourceDescType | - type of the resource description. The type must have operator== and a hash function defined.

Remarks
  The following strategies do not work:
  - To store raw pointers and remove the object from the registry in the object's destructor. In this case other thread may obtain a reference to the object while it is being deleted. This scenario is possible if one thread has just entered the destructor, but other is executing Find() and entered the protection section.
  - Strong pointers will cause circular references and result in memory leaks.
  Only weak pointers provide thread-safe solution. The object is either atomically destroyed, so that no other thread can obtain a reference to it through weak pointers. Or it is atomically locked, so that strong reference is obtained. In this case no other thread can destroy the object, because there is at least one strong reference now. Note however that removing the object from the registry in the object's destructor may cause a deadlock at the point where Find() locks the weak pointer: if other thread has started dtor, the object will be locked by Diligent::RefCountedObject::Release(). If after that this thread locks the registry first, it will be waiting for the object to unlock in Diligent::RefCntWeakPtr::Lock(), while the dtor thread will be waiting for the registry to unlock.

## Member Function Documentation

## ◆ Add()

template<typename ResourceDescType>

void Diligent::StateObjectsRegistry< ResourceDescType >::Add | ( | const ResourceDescType & | ObjectDesc,
|  | IDeviceObject * | pObject
| ) |  |
| inline

Adds a new object to the registry.

Parameters

  [in] | ObjectDesc | - object description.
  [in] | pObject | - pointer to the object.

Besides adding a new object, the function also checks the number of outstanding deleted objects and calls Purge() if the number has reached the threshold value DeletedObjectsToPurge. Creating a state object is assumed to be an expensive operation and should be performed during the initialization. Occasional purge operations should not add significant cost to it.