TurtleBrains::Core::ResourceCache< ResourceType, HandleType > Class Template Reference

#include <tb_resource_cache.hpp>

Inheritance diagram for TurtleBrains::Core::ResourceCache< ResourceType, HandleType >:

Public Member Functions
HandleType	CreateResource (const ResourceType &resource, const tbCore::tbString &resourceName="")
void	DestroyResource (const HandleType &handle)
void	ClearCache (void)
void	IncrementReferenceOf (const HandleType &handle)
bool	DecrementReferenceOf (const HandleType &handle)
ResourceType	GetResource (const HandleType &handle) const
void	SetResource (const HandleType &handle, const ResourceType &resource)
const ResourceType &	GetResourceReference (const HandleType &handle) const
ResourceType &	GetResourceReference (const HandleType &handle)
HandleType	GetResourceHandle (const tbCore::tbString &resourceName) const
bool	IsValidHandle (const HandleType &handle) const
size_t	ForEachValidResource (std::function< void(ResourceType &, HandleType)> callbackFunction)

Static Public Member Functions
static HandleType	InvalidResource (void)

Detailed Description

template<typename ResourceType, typename HandleType>
class TurtleBrains::Core::ResourceCache< ResourceType, HandleType >

Provides and interface for caching resources by name; sharing a single instance of a resource with multiple users/end-points. The ResourceCache does NOT manage the creation or destruction/cleanup of the resources that it contains. It simple provides tracking by name (often filepath) and reference counting.

Member Function Documentation

template<typename ResourceType , typename HandleType >

void TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::ClearCache

(

void

)

Nuclear option to remove everything from the cache immediately. This will invalidate ALL handles that belong to the cache even if the reference count is above 0.

Note

This removes EVERYTHING without care about reference counted resources and was expected that the resource data has already been cleaned up as the ResourceCache does not manage this.

template<typename ResourceType , typename HandleType >

HandleType TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::CreateResource	(	const ResourceType &	resource,
		const tbCore::tbString &	resourceName = ""
	)

Creates (or adds) a resource to the resource cache; optionally tracked by a name for ensuring only one copy of the resource will exist for that name. Once added/created the resource will have exactly 1 reference automatically.

Parameters

resource	The resource data to add to the caching system, the resource should have been allocated and setup before calling this.
resourceName	Optional name for the resource to ensure multiple copies of the same resource use a single instance. If the name is left empty it will be free to be copied, or one can use IncrementReferenceCount to manually share without name.

Note

One should ensure no resouce with the resourceName exists before calling CreateResource, and the resource cache is not responsible for the creation/allocation/setup of the resource being added/created.

template<typename ResourceType , typename HandleType >

bool TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::DecrementReferenceOf

(

const HandleType &

handle

)

Decrements the reference count for a resource handle and returns true when the refence count for the handle reaches 0. When true is returned it is expected that the resource gets cleaned up and DestroyResource is then called for it to be removed.

Parameters

handle

A handle to the resource that should remove a reference.

Note

When true is returned, the handle is technically invalid without being completely invalidated until DestroyResource is called, and before DestroyResource is called the resource needs to be cleaned up.

template<typename ResourceType , typename HandleType >

void TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::DestroyResource

(

const HandleType &

handle

)

Destroys (or removes) a resource from the resource cache. Note that the resource cache is NOT responsible for the destrucion/cleanup of the resource being removed, in fact it should probably happen immediately before this is called.

Parameters

handle

A handle to the resource that should be destroyed/removed from the ResourceCache. If the handle is invalid or not contained in the cache an error condition will be triggered.

template<typename ResourceType , typename HandleType >

ResourceType TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::GetResource

(

const HandleType &

handle

)

const

Returns a copy of the resource for manipulation as needed.

Parameters

handle

A handle to the resource that should be retreived. If the handle is invalid or not contained within the ResouceCache and error condition will be triggered.

Note

Because this returns a copy, if the copy gets modified it needs to be set in the cache by calling SetResource when finished.

template<typename ResourceType , typename HandleType >

HandleType TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::GetResourceHandle

(

const tbCore::tbString &

resourceName

)

const

Returns the resource handle associated with a resourceName. If the handle is invalid it means the ResourceCache does not have a resource with that name.

Parameters

resourceName

The name of the resource to search for.

Note

One should call this before adding/creating a resource with CreateResource().

template<typename ResourceType , typename HandleType >

const ResourceType & TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::GetResourceReference

(

const HandleType &

handle

)

const

Returns the resource data by reference so it can be modified in place.

Parameters

handle

A handle to the resource that should be retreived. If the handle is invalid or not contained within the ResouceCache and error condition will be triggered.

Note

This is less safe than GetResource()/SetResource(). Use caution when using as adding or removing from the resouce cache while holding a reference to data may cause undefined behavior.

This is NOT thread-safe, do NOT use when your ResourceCache object must be thread-safe.

template<typename ResourceType , typename HandleType >

ResourceType & TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::GetResourceReference

(

const HandleType &

handle

)

Returns the resource data by reference so it can be modified in place.

Parameters

handle

A handle to the resource that should be retreived. If the handle is invalid or not contained within the ResouceCache and error condition will be triggered.

Note

This is less safe than GetResource()/SetResource(). Use caution when using as adding or removing from the resouce cache while holding a reference to data may cause undefined behavior.

This is NOT thread-safe, do NOT use when your ResourceCache object must be thread-safe.

template<typename ResourceType , typename HandleType >

void TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::IncrementReferenceOf

(

const HandleType &

handle

)

Increments the reference count for a valid resource handle so that a single resource instance can be shared with multiple parties.

Parameters

handle

A handle to the resource that should have an additional reference added.

Note

For every IncrementReferenceOf() a matching DecrementReferenceOf() must be called to perform proper cleanup. The CreateResource() function starts a resource with 1 reference already.

template<typename ResourceType , typename HandleType >

HandleType TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::InvalidResource ( void  )

static

Returns a ResourceHandle that is marked invalid for comparing against.

template<typename ResourceType , typename HandleType >

bool TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::IsValidHandle

(

const HandleType &

handle

)

const

Checks a handle for validity and containment within the ResourceCache and returns true if valid, or false if invalid or not contained.

Parameters

handle

The handle to check if it is a valid handle with the ResouceCache.

template<typename ResourceType , typename HandleType >

void TurtleBrains::Core::ResourceCache< ResourceType, HandleType >::SetResource	(	const HandleType &	handle,
		const ResourceType &	resource
	)

Changes the data of a resource for the given handle which is expected to be valid.

Parameters

handle	A handle to the resource that should be retreived. If the handle is invalid or not contained within the ResouceCache and error condition will be triggered.
resource	The resource data to set to the caching system, replacing the old data for this handle.