Ceylan::BasicResourceManager< Key > Class Template Reference

Manages basically a set of Resource instances: the basic Resource manager can store and afterwards retrieve resources on behalf of the caller, which will be able to associate a key, whose type is user-defined, to each resource. More...

#include <CeylanBasicResourceManager.h>

Inheritance diagram for Ceylan::BasicResourceManager< Key >:
Inheritance graph
[legend]
Collaboration diagram for Ceylan::BasicResourceManager< Key >:
Collaboration graph
[legend]

List of all members.

Public Types

enum  TextOutputFormat { rawText, html }
 

Defines what text output formats for TextDisplayable instances are available.

More...

Public Member Functions

 BasicResourceManager ()
 Creates a new Resource manager, which will store, take ownership of and make available the resources that it will be given, with no concern for size limit.
virtual ~BasicResourceManager () throw ()
 Virtual destructor, deletes all resources still in cache.
virtual void takeOwnershipOf (const Key &key, const Resource &resource)
 Puts specified resource in cache, associated with specified key, and takes ownership of it.
virtual bool isKeyAlreadyAssociated (const Key &key) const
 Tells whether the specified key is already associated with a Resource.
virtual const Resourceget (const Key &key)
 Returns directly the resource associated with this key, if available in cache.
virtual void flush ()
 Removes and deletes all resources currently in cache.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns a user-friendly description of the state of this object.

Static Public Member Functions

static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.

Protected Attributes

std::map< Key, const Resource * > _entries
 Stores the association between a key and a resource.
Ceylan::Uint32 _cacheHits
 Records the total number of requested resources successfully found in cache.
Ceylan::Uint32 _cacheMisses
 Records the total number of requested resources not found in cache.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.

Private Member Functions

 BasicResourceManager (const BasicResourceManager &source)
 Copy constructor made private to ensure that it will never be called.
BasicResourceManageroperator= (const BasicResourceManager &source)
 Assignment operator made private to ensure that it will never be called.

Detailed Description

template<typename Key>
class Ceylan::BasicResourceManager< Key >

Manages basically a set of Resource instances: the basic Resource manager can store and afterwards retrieve resources on behalf of the caller, which will be able to associate a key, whose type is user-defined, to each resource.

The basic Resource manager takes ownership of the Resources it is given, it stores them all and, on request, thanks to the key, delivers to the caller only const references to these resources.

Such managers are especially designed to facilitate the memory management of static user resources, such as sounds, textures, maps, geometries, etc.

A Resource manager handles the life cycle of its resources: it takes their ownership, which means it will delete them when itself deleted. From the user's point of view, giving a Resource to the manager thanks to the 'takeOwnershipOf' method is an alternative to deleting the resource. By no means should the caller delete a managed Resource. Modifying them after having given them this way to the manager is not recommended: the caller should forget any pointer or reference to the Resources it sent to the manager, so that these resources remain unaltered and can be directly retrieved 'as are' by various cache users.

The resources can be submitted to the manager at the time when their state must be kept, including prior to any use or after they already have been used, at the moment when they would have been deallocated, should there be no cache.

The basic Resource manager has no quota to respect, it will store all given Resources regardless of the resulting size in memory, and will make them available (as const resources), as long as the manager exists: a basic manager will never forget any resource while still alive.

There are different use cases for such a manager, depending on what is to be done with the cached resources, which translates into the need for cached resources to be cloned or not.

If we take the example of a font rendering system, then this type of cache could be useful when the blitting of a glyph is requested: first the specified glyph is rendered into a new surface, then it is blitted on, say, the screen. Instead of deallocating the surface after use, the blit function could pass it to an appropriate resource manager, which would take ownership of it. If later the same blitting is requested again, then the blit function could start by asking the cache for this prerendered glyph. The cache, if fed as described before, should be able to provide it as a 'const' resource, which could be used directly for the targeted blit.

This will work as long as the user ensures that none of these 'const' resources is used after the manager is deleted.

Note:
No CEYLAN_DLL declaration for templates.

Definition at line 96 of file CeylanBasicResourceManager.h.


Member Enumeration Documentation

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.


Constructor & Destructor Documentation

template<typename Key >
Ceylan::BasicResourceManager< Key >::BasicResourceManager (  )  [inline, explicit]

Creates a new Resource manager, which will store, take ownership of and make available the resources that it will be given, with no concern for size limit.

As no resource will be ever dropped until the manager is deleted, it is the user responsibility to take care of how much data is put in cache, so that the total size in memory does not increase too much.

Definition at line 265 of file CeylanBasicResourceManager.h.

template<typename Key >
Ceylan::BasicResourceManager< Key >::~BasicResourceManager (  )  throw () [inline, virtual]

Virtual destructor, deletes all resources still in cache.

There does not seem to exist any way of calling 'flush' from the abstract mother class so that no child class could forget to call it.

Definition at line 275 of file CeylanBasicResourceManager.h.

template<typename Key >
Ceylan::BasicResourceManager< Key >::BasicResourceManager ( const BasicResourceManager< Key > &  source  )  [private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.


Member Function Documentation

template<typename Key >
void Ceylan::BasicResourceManager< Key >::flush (  )  [inline, virtual]

Removes and deletes all resources currently in cache.

Cache statistics are not modified.

Implements Ceylan::ResourceManager< Key >.

Definition at line 354 of file CeylanBasicResourceManager.h.

template<typename Key >
const Resource * Ceylan::BasicResourceManager< Key >::get ( const Key &  key  )  [inline, virtual]

Returns directly the resource associated with this key, if available in cache.

Otherwise returns a null pointer.

Returns:
A 'const' resource since it must not be changed in any way by the caller (not modified, not deallocated, etc.) so that the version in cache remains untouched. Similarly, no entry with the same key must be put in cache nor the cache itself must be deallocated while a returned resource is in use, since it would result in the deallocation of this resource.
Note:
The method itself cannot be 'const' since some metadata in cache entries might be updated. Maybe the volatile keyword should be used for such attributes.

Implements Ceylan::ResourceManager< Key >.

Definition at line 332 of file CeylanBasicResourceManager.h.

References Ceylan::BasicResourceManager< Key >::_entries.

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]
template<typename Key >
bool Ceylan::BasicResourceManager< Key >::isKeyAlreadyAssociated ( const Key &  key  )  const [inline, virtual]

Tells whether the specified key is already associated with a Resource.

Useful to avoid trying to overwrite a resource already associated with a key.

Implements Ceylan::ResourceManager< Key >.

Definition at line 320 of file CeylanBasicResourceManager.h.

template<typename Key >
BasicResourceManager& Ceylan::BasicResourceManager< Key >::operator= ( const BasicResourceManager< Key > &  source  )  [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

template<typename Key >
void Ceylan::BasicResourceManager< Key >::takeOwnershipOf ( const Key &  key,
const Resource resource 
) [inline, virtual]

Puts specified resource in cache, associated with specified key, and takes ownership of it.

The basic Resource manager takes ownership of all the supplied resources and will perform their deleting only during its own deleting, or when the 'flush' method is called.

Parameters:
key the key by which that resource could be retrieved. If this key is already associated with a resource, an exception is raised.
resource the resource to put in cache. It must be a dynamically allocated resource (thanks to new, no automatic variable) since it will be deallocated by the cache when deemed appropriate.
Exceptions:
ResourceManagerException if the specified key was already associated with a Resource.
See also:
isKeyAlreadyAssociated

Definition at line 290 of file CeylanBasicResourceManager.h.

const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

template<typename Key >
const std::string Ceylan::BasicResourceManager< Key >::toString ( Ceylan::VerbosityLevels  level = Ceylan::high  )  const [inline, virtual]

Returns a user-friendly description of the state of this object.

Parameters:
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
TextDisplayable

Reimplemented from Ceylan::ResourceManager< Key >.

Definition at line 370 of file CeylanBasicResourceManager.h.


Member Data Documentation

template<typename Key >
Ceylan::Uint32 Ceylan::ResourceManager< Key >::_cacheHits [protected, inherited]
template<typename Key >
Ceylan::Uint32 Ceylan::ResourceManager< Key >::_cacheMisses [protected, inherited]

Records the total number of requested resources not found in cache.

Definition at line 237 of file CeylanResourceManager.h.

Referenced by Ceylan::SmartResourceManager< Key >::get(), Ceylan::SmartResourceManager< Key >::toString(), and Ceylan::ResourceManager< Key >::toString().

template<typename Key >
std::map<Key, const Resource *> Ceylan::BasicResourceManager< Key >::_entries [protected]

Stores the association between a key and a resource.

Definition at line 164 of file CeylanBasicResourceManager.h.

Referenced by Ceylan::BasicResourceManager< Key >::get().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().


The documentation for this class was generated from the following file:
Generated on Mon Nov 29 13:40:19 2010 for Ceylan by  doxygen 1.6.3