Ceylan::ResourceManager< Key > Class Template Reference
Manages a set of Resource instances: the Resource manager can store and afterwards retrieve resources on behalf of the caller, which will associate a key, whose type is user-defined, to each resource. More...
#include <CeylanResourceManager.h>
Public Types | |
| enum | TextOutputFormat { rawText, html } |
| Defines what text output formats for TextDisplayable instances are available. More... | |
Public Member Functions | |
| ResourceManager () | |
| Creates an abstract Resource manager. | |
| virtual | ~ResourceManager () throw () |
| Virtual destructor, deletes all resources still in cache. | |
| virtual bool | isKeyAlreadyAssociated (const Key &key) const =0 |
| Returns whether the specified key is already associated with a Resource. | |
| virtual const Resource * | get (const Key &key)=0 |
| Returns directly the resource associated with this key, if available in cache. | |
| virtual void | flush ()=0 |
| 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 | |
| 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 | |
| ResourceManager (const ResourceManager &source) | |
| Copy constructor made private to ensure that it will never be called. | |
| ResourceManager & | operator= (const ResourceManager &source) |
| Assignment operator made private to ensure that it will be never called. | |
Detailed Description
template<typename Key>
class Ceylan::ResourceManager< Key >
Manages a set of Resource instances: the Resource manager can store and afterwards retrieve resources on behalf of the caller, which will associate a key, whose type is user-defined, to each resource.
The Resource manager takes ownership of the Resources it is given, 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 resources.
This abstract manager is the mother class of all resource managers.
A Resource manager handles the life cycle of its resources: it takes their ownership, which means it will delete them when itself deleted or flushed. From the user's point of view, giving a Resource to the manager is an alternative to deleting the resource. By no means should the caller delete a managed Resource. Modifying them after having given them to the manager is not recommended: the caller should forget any pointer or reference to the Resources it sent to the manager.
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 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), as long as the manager exists: it will never forget any resource while still alive.
There are different use cases for such a cache, 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 be used after the manager deleting.
As no direct inheritance relationship can exist between the basic and smart managers (for example, the 'takeOwnershipOf' method should not have the same parameters, respectively it should be 'Resource' and 'SmartResource'), this abstract class is needed.
In all templates inheriting from this one, the data members (ex: _cacheHits) should be specified as 'this->_cacheHits' or 'CeylanResourceManager<Key>::_cacheHits', since otherwise the compiler would not search for these member names in this mother class: it may not contain a '_cacheHits' member for all 'Key' choice, because of template specialization that may occur.
- Note:
- No CEYLAN_DLL declaration for templates.
Definition at line 134 of file CeylanResourceManager.h.
Member Enumeration Documentation
enum Ceylan::TextDisplayable::TextOutputFormat [inherited] |
Defines what text output formats for TextDisplayable instances are available.
Definition at line 124 of file CeylanTextDisplayable.h.
Constructor & Destructor Documentation
| Ceylan::ResourceManager< Key >::ResourceManager | ( | ) | [inline, explicit] |
Creates an abstract Resource manager.
Public section: implementation.
Definition at line 273 of file CeylanResourceManager.h.
| Ceylan::ResourceManager< Key >::~ResourceManager | ( | ) | throw () [inline, virtual] |
Virtual destructor, deletes all resources still in cache.
- Note:
- Each child class should have its destructor call the 'flush' method.
Definition at line 282 of file CeylanResourceManager.h.
| Ceylan::ResourceManager< Key >::ResourceManager | ( | const ResourceManager< 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
| virtual void Ceylan::ResourceManager< Key >::flush | ( | ) | [pure virtual] |
Removes and deletes all resources currently in cache.
Cache statistics are not modified.
- Note:
- Should be called in the destructor of each child class.
Implemented in Ceylan::BasicResourceManager< Key >, and Ceylan::SmartResourceManager< Key >.
| virtual const Resource* Ceylan::ResourceManager< Key >::get | ( | const Key & | key | ) | [pure 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.
Implemented in Ceylan::BasicResourceManager< Key >, and Ceylan::SmartResourceManager< Key >.
| TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat | ( | ) | [static, inherited] |
Returns the current overall text format to be used by TextDisplayable instances.
Definition at line 63 of file CeylanTextDisplayable.cc.
References Ceylan::TextDisplayable::_OutputFormat.
Referenced by Ceylan::formatStringList(), Ceylan::formatStringMap(), Ceylan::XML::XMLMarkup::toString(), Ceylan::Maths::Linear::Vector3::toString(), Ceylan::Maths::Linear::Vector2::toString(), Ceylan::Maths::Linear::Tripoint::toString(), Ceylan::Module::toString(), Ceylan::Maths::Linear::Matrix3::toString(), Ceylan::Maths::Linear::Matrix2::toString(), Ceylan::Maths::Linear::HomogeneousMatrix3::toString(), and Ceylan::Maths::Linear::Bipoint::toString().
| virtual bool Ceylan::ResourceManager< Key >::isKeyAlreadyAssociated | ( | const Key & | key | ) | const [pure virtual] |
Returns whether the specified key is already associated with a Resource.
Useful to avoid trying to overwrite a resource already associated with a key.
Implemented in Ceylan::BasicResourceManager< Key >, and Ceylan::SmartResourceManager< Key >.
| ResourceManager& Ceylan::ResourceManager< Key >::operator= | ( | const ResourceManager< Key > & | source | ) | [private] |
Assignment operator made private to ensure that it will be never 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().
| 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().
| const std::string Ceylan::ResourceManager< 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
Implements Ceylan::TextDisplayable.
Reimplemented in Ceylan::BasicResourceManager< Key >, and Ceylan::SmartResourceManager< Key >.
Definition at line 295 of file CeylanResourceManager.h.
References Ceylan::ResourceManager< Key >::_cacheHits, Ceylan::ResourceManager< Key >::_cacheMisses, dataUtils::f, Ceylan::low, and Ceylan::toNumericalString().
Member Data Documentation
Ceylan::Uint32 Ceylan::ResourceManager< Key >::_cacheHits [protected] |
Records the total number of requested resources successfully found in cache.
Definition at line 229 of file CeylanResourceManager.h.
Referenced by Ceylan::ResourceManager< Key >::toString().
Ceylan::Uint32 Ceylan::ResourceManager< Key >::_cacheMisses [protected] |
Records the total number of requested resources not found in cache.
Definition at line 237 of file CeylanResourceManager.h.
Referenced by Ceylan::ResourceManager< Key >::toString().
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:
