Ceylan::SmartResourceManager< Key > Class Template Reference
Manages a set of SmartResource instances: the smart Resource manager can behave like a basic Resource manager, if the 'NeverDrop' policy is used, or it can provide other advanced policies. More...
#include <CeylanSmartResourceManager.h>
Classes | |
| struct | CacheEntry |
| Metadata associated to a cached resource. More... | |
Public Types | |
| enum | CachePolicy { NeverDrop, DropLessRequestedFirst } |
| Lists all available cache policies:. More... | |
Public Member Functions | |
| SmartResourceManager () | |
| Creates a new smart resource manager, which will store, take ownership of and make available the resources that will be put in it, with the 'NeverDrop' policy, i.e. | |
| SmartResourceManager (System::Size quota, CachePolicy policy=DropLessRequestedFirst) | |
| Creates a new smart resource manager, which will store and make available resources, with respect to the specified quota and the specified policy. | |
| virtual | ~SmartResourceManager () throw () |
| Virtual destructor, deletes all owned resources still in cache. | |
| virtual bool | scanForAddition (const Key &key, const SmartResource &smartResource) |
| Puts, if possible, a clone of specified resource in cache, associated with specified key, without taking ownership of the specified resource. | |
| virtual bool | takeOwnershipOf (const Key &key, const SmartResource &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 SmartResource * | getClone (const Key &key) |
| Returns a clone of the resource associated with this key, if available in cache. | |
| virtual const Resource * | get (const Key &key) |
| Returns directly the smart resource associated with this key, if available in cache. | |
| virtual System::Size | getQuota () const |
| Returns the smart resource manager current quota, in bytes. | |
| virtual CachePolicy | getCachePolicy () const |
| Returns the cache policy currently being enforced. | |
| virtual System::Size | getFootprint () const |
| Returns the approximate size of the memory used by all currently cached resources, in bytes. | |
| virtual void | update () |
| Updates the cache metadata: recomputes the size in memory of each cache entry, and applies the selected cache policy. | |
| virtual void | updateSizes () |
| Recomputes the size in memory of each cache entry. | |
| virtual void | applyPolicy () |
| Applies the current policy on cache entries. | |
| 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 Member Functions | |
| virtual void | applyPolicy (const SmartResource *lastCached) |
| Applies the current policy. | |
| virtual void | applyDropLessRequestedFirst (const SmartResource *lastCached=0) |
| Applies the 'DropLessRequestedFirst' policy on current cached entries. | |
| virtual void | addEntry (const Key &key, const SmartResource &newResource, Ceylan::System::Size size=0) |
| Adds a new cached entry, with the specified resource and key. | |
| virtual void | dropEntryDueToPolicy (typename std::map< Key, CacheEntry * >::iterator pos) |
| Drops specified cache entry: helper for cache policy execution. | |
| virtual void | dropEntry (typename std::map< Key, CacheEntry * >::iterator pos) |
| Drops specified cache entry. | |
Protected Attributes | |
| System::Size | _quota |
| The quota that would be enforced by this cache, provided that a policy makes us of it. | |
| System::Size | _totalSize |
| The approximate total size of all cached resources, as computed after last resource inspection and updated on drop/put operations. | |
| CachePolicy | _policy |
| The policy enforced by this cache. | |
| Ceylan::Uint32 | _droppedByPolicy |
| Records the total number of resources dropped by this manager because of cache policy (counting neither resource replacements because of key collision nor the final drops caused by manager deleting). | |
| std::map< Key, CacheEntry * > | _entries |
| 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 | |
| SmartResourceManager (const SmartResourceManager &source) | |
| Copy constructor made private to ensure that it will never be called. | |
| SmartResourceManager & | operator= (const SmartResourceManager &source) |
| Assignment operator made private to ensure that it will never be called. | |
Detailed Description
template<typename Key>
class Ceylan::SmartResourceManager< Key >
Manages a set of SmartResource instances: the smart Resource manager can behave like a basic Resource manager, if the 'NeverDrop' policy is used, or it can provide other advanced policies.
For all policies, supplementary means of storing resources in the cache and retrieving them are provided. These new functionalities are allowed thanks to the ability of smart resources to compute themselves their size and to be cloned.
Various ownerships and 'const'-ness for the submitted and returned resources can be chosen, so that only the necessary resource clones are created.
Basically, besides the inherited way of storing a resource ('takeOwnershipOf' method), smart resources can be cloned, and have their clone stored into the cache, so that the caller keeps the ownership of the submitted resource and the possibility to modify it afterwards: the smart manager just reads the specified resource and, if its policy tells this resource can be cached, it makes a clone of it so that it can store this copy for later use, without changing in any way the specified resource and what the user can do with it. The 'scanForAddition' method corresponds to this alternative to the 'takeOwnershipOf' method.
Similarly, to the inherited way of retrieving a resource from cache (the 'get' method, which returns only a 'const' resource) is added a new method ('getClone'), which returns a clone of the resource specified by a key. The ownership of the clone is transferred to the caller, who will be able to modify it at will, and will have to delete it, once finished with it.
Various cache policies can be chosen to limit the size in memory taken by the resources cached by a smart manager.
If the smart Resource manager has to enforce a quota (an upper bound to the total memory size of cached resources), it will have to drop cached entries based on the current cache policy, whose role is to select which resources should be kept and which should be dropped.
Specifying a policy enforcing a quota implies that resources can be dropped and thus that the application is able to regenerate them when needed: in this case the application can never rely on the cache to answer to a given request, even if the corresponding entry had been recently submitted to the cache. It is the price for memory control.
As computing resource sizes may be demanding, they are recomputed only on request ('updateSizes' method), otherwise the size taken into account for a resource is the one it had when lastly managed by the cache.
A smart Resource manager handles the life cycle of the resources whose ownership has been given to it: it will deallocate them when itself deleted, or sooner for various reasons, including if having a quota to respect and needing some more room.
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.
For each use case, both the way of submitting the resource (hereby called a 'put' operation, be it 'takeOwnershipOf' or 'scanForAddition'), and of retrieving them (a 'get' operation, be it 'get' or 'getClone'), have to be carefully chosen. All combinations are valid, there are just 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, we saw with basic ResourceManager how a 'takeOwnershipOf'/'get' pair could be useful. On the contrary of a mere blit, if a glyph is needed but will be altered after its creation, then when this surface is in some particular state, the user may would like to have it cached. In this case, the user will submit that surface to the cache, asking that the cache does not take the ownership of it, but makes a clone of it, so that the user can keep on using his surface. This can be done thanks to the 'scanForAddition' method. If the cache is able to store this smart resource, then it will clone it and store the clone. The submitted surface will not be modified in any way. If the key associated to this surface is requested afterwards, then, if still in cache, it will be returned, either as 'const Resource' or as a non-const resource (hence a clone of the initial clone), depending on the choice of the caller ('get' or 'getClone').
Such an organization allows to clone the resource only if needed, i.e. only when the manager knows for sure that the resource will be accepted in cache with regard to its state and the current cache policy being applied. Otherwise a resource could be cloned before knowing whether the clone can be accepted in cache, hence leading to useless cloning operations.
The SmartResourceManager class should not be a child class of the BasicResourceManager class, since it must deal with smart resources only. However its 'NeverDrop' policy results in a behaviour very similar to the one of a basic Resource manager.
- Note:
- No CEYLAN_DLL declaration for templates.
Definition at line 148 of file CeylanSmartResourceManager.h.
Member Enumeration Documentation
| enum Ceylan::SmartResourceManager::CachePolicy |
Lists all available cache policies:.
- 'NeverDrop': no quota enforced, no resource dropped, except on manager deleting or explicit 'flush' request. If a 'put' operation would lead to an already cached resource being replaced by another resource associated to the same key, a ResourceManagerException is raised. Therefore the only cause for a non-cloned (const resource) returned by a 'get' operation to become invalid is the resource manager being deleted (or flushed): its life cycle must therefore be correctly managed by the user.
- 'DropLessRequestedFirst': the manager may drop resources for three reasons. If the quota is reached, it will drop the less requested resources, no matter their size in memory (but if this policy is applied as part of a 'put' operation, the newly cached resource will escape this first drop round). If a resource is put with a key already associated with a previously put resource, the new resource will replace the previous one, which will be dropped. If the manager is deleted or flushed, all resources will be dropped.
There is a drawback with such templated enumerations: user code cannot specify a cache policy independently of the type of the key chosen for the template instanciation. For example, a cache policy cannot be specified as SmartResourceManager::CachePolicy, it has to be for example SmartResourceManager<int>::CachePolicy. In this case, SmartResourceManager<float>::CachePolicy is a completely different type, which can be a bit inconvenient. See OSDL::Font to have an example of issue and work-around.
Definition at line 191 of file CeylanSmartResourceManager.h.
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::SmartResourceManager< Key >::SmartResourceManager | ( | ) | [inline, explicit] |
Creates a new smart resource manager, which will store, take ownership of and make available the resources that will be put in it, with the 'NeverDrop' policy, i.e.
with no concern for size limit, as a basic ResourceManager would do.
As no resource will be ever dropped until the manager is flushed or deleted, it is the user responsibility to take care of what is put in cache, so that the total size in memory does not increase too much.
Definition at line 687 of file CeylanSmartResourceManager.h.
| Ceylan::SmartResourceManager< Key >::SmartResourceManager | ( | System::Size | quota, | |
| CachePolicy | policy = DropLessRequestedFirst | |||
| ) | [inline, explicit] |
Creates a new smart resource manager, which will store and make available resources, with respect to the specified quota and the specified policy.
It implies dropping a smart Resource if the cache policy determines it.
- Parameters:
-
quota the upper bound of the total size of cached resources in memory, if the selected policy takes it into account. No default value is provided since it depends too much on the resources being actually cached. policy the cache policy to enforce.
Definition at line 701 of file CeylanSmartResourceManager.h.
| Ceylan::SmartResourceManager< Key >::~SmartResourceManager | ( | ) | throw () [inline, virtual] |
Virtual destructor, deletes all owned 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 716 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::flush().
| Ceylan::SmartResourceManager< Key >::SmartResourceManager | ( | const SmartResourceManager< 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
| void Ceylan::SmartResourceManager< Key >::addEntry | ( | const Key & | key, | |
| const SmartResource & | newResource, | |||
| Ceylan::System::Size | size = 0 | |||
| ) | [inline, protected, virtual] |
Adds a new cached entry, with the specified resource and key.
If the key is already associated with a cache entry, this cache entry will be deleted first, including its embedded resource.
- Parameters:
-
key the key for this new cache entry. If the key is already assigned in the cache, the previous entry is erased first. newResource the smart resource which should be cached. size the size of this resource, if not null (allows to avoid useless size recomputations, since they might be demanding). If null, the actual size will be computed on the fly.
- Exceptions:
-
ResourceManagerException if the policy is 'NeverDrop' and the key is already associated to a resource. In this case, the association remains untouched.
Definition at line 1251 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries, Ceylan::SmartResourceManager< Key >::_policy, Ceylan::SmartResourceManager< Key >::SmartResourceManager::CacheEntry::_requestCount, Ceylan::SmartResourceManager< Key >::SmartResourceManager::CacheEntry::_resource, Ceylan::SmartResourceManager< Key >::SmartResourceManager::CacheEntry::_size, Ceylan::SmartResourceManager< Key >::_totalSize, Ceylan::SmartResourceManager< Key >::dropEntry(), Ceylan::Measurable::getSizeInMemory(), and Ceylan::SmartResourceManager< Key >::NeverDrop.
Referenced by Ceylan::SmartResourceManager< Key >::scanForAddition(), and Ceylan::SmartResourceManager< Key >::takeOwnershipOf().
| void Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst | ( | const SmartResource * | lastCached = 0 |
) | [inline, protected, virtual] |
Applies the 'DropLessRequestedFirst' policy on current cached entries.
Definition at line 1160 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries, Ceylan::SmartResourceManager< Key >::_quota, Ceylan::SmartResourceManager< Key >::dropEntryDueToPolicy(), generalUtils::false, Ceylan::SmartResourceManager< Key >::getFootprint(), and generalUtils::true.
Referenced by Ceylan::SmartResourceManager< Key >::applyPolicy().
| void Ceylan::SmartResourceManager< Key >::applyPolicy | ( | const SmartResource * | lastCached | ) | [inline, protected, virtual] |
Applies the current policy.
- Parameters:
-
lastCached,if non null, indicates that the policy is being applied just upon this last resource has been put in cache, and therefore this resource should be preserved from this first shrink. If lastCached is null, the policy will be applied uniformly against all cache entries.
Definition at line 1133 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_policy, Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst(), Ceylan::SmartResourceManager< Key >::DropLessRequestedFirst, Ceylan::emergencyShutdown(), and Ceylan::SmartResourceManager< Key >::NeverDrop.
| void Ceylan::SmartResourceManager< Key >::applyPolicy | ( | ) | [inline, virtual] |
Applies the current policy on cache entries.
- Note:
- The size which is taken into account is based onto the metadata of the entries, which may be out-of-date. If one wants the cache policy to rely on accurate sizes, the 'updateSizes' method should be called first.
Definition at line 951 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::scanForAddition(), Ceylan::SmartResourceManager< Key >::takeOwnershipOf(), and Ceylan::SmartResourceManager< Key >::update().
| void Ceylan::SmartResourceManager< Key >::dropEntry | ( | typename std::map< Key, CacheEntry * >::iterator | pos | ) | [inline, protected, virtual] |
Drops specified cache entry.
- Parameters:
-
pos the iterator pointing to the cache entry to drop.
Definition at line 1318 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries, and Ceylan::SmartResourceManager< Key >::_totalSize.
Referenced by Ceylan::SmartResourceManager< Key >::addEntry(), and Ceylan::SmartResourceManager< Key >::dropEntryDueToPolicy().
| void Ceylan::SmartResourceManager< Key >::dropEntryDueToPolicy | ( | typename std::map< Key, CacheEntry * >::iterator | pos | ) | [inline, protected, virtual] |
Drops specified cache entry: helper for cache policy execution.
Should be called by all methods applying a policy such as 'applyDropLessRequestedFirst' (since this method does everything needed), and only by them (since it updates the statistics of drop-because-of-policy as well).
- Parameters:
-
pos the iterator pointing to the cache entry to drop.
Definition at line 1306 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_droppedByPolicy, and Ceylan::SmartResourceManager< Key >::dropEntry().
Referenced by Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst().
| void Ceylan::SmartResourceManager< Key >::flush | ( | ) | [inline, virtual] |
Removes and deletes all resources currently in cache.
Cache statistics are not modified.
Implements Ceylan::ResourceManager< Key >.
Definition at line 1001 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries, and Ceylan::SmartResourceManager< Key >::_totalSize.
Referenced by Ceylan::SmartResourceManager< Key >::~SmartResourceManager().
| const Resource * Ceylan::SmartResourceManager< Key >::get | ( | const Key & | key | ) | [inline, virtual] |
Returns directly the smart resource associated with this key, if available in cache.
Otherwise returns a null pointer.
The signature of this inherited method tells it returns Resource instances, but more precisely in the case of a smart manager it will be always SmartResource instances.
- Returns:
- A 'const' resource since it must not be changed in any way by the caller (not modified nor deallocated, etc.) so that the version in cache remains unaltered. 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.
Implements Ceylan::ResourceManager< Key >.
Definition at line 977 of file CeylanSmartResourceManager.h.
References Ceylan::ResourceManager< Key >::_cacheHits, Ceylan::ResourceManager< Key >::_cacheMisses, and Ceylan::SmartResourceManager< Key >::_entries.
| Ceylan::SmartResourceManager< Key >::CachePolicy Ceylan::SmartResourceManager< Key >::getCachePolicy | ( | ) | const [inline, virtual] |
Returns the cache policy currently being enforced.
Definition at line 747 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_policy.
| SmartResource * Ceylan::SmartResourceManager< Key >::getClone | ( | const Key & | key | ) | [inline, virtual] |
Returns a clone of the resource associated with this key, if available in cache.
Otherwise returns a null pointer.
Cloning, even if it is complex or resource-demanding, is necessary since with this method the caller should be able to do anything with the returned resource, including modifying it and/or deallocating it independently from the resource manager and its life cycle.
- Note:
- This ethod cannot be 'const' since some metadata in cache entries might be updated.
Definition at line 878 of file CeylanSmartResourceManager.h.
References Ceylan::ResourceManager< Key >::_cacheHits, Ceylan::SmartResourceManager< Key >::_entries, and Ceylan::emergencyShutdown().
| System::Size Ceylan::SmartResourceManager< Key >::getFootprint | ( | ) | const [inline, virtual] |
Returns the approximate size of the memory used by all currently cached resources, in bytes.
The size of the smart resource manager itself is not taken into account in the sum. In most cases its size is negligible compared to the total resource size.
- Note:
- The sizes taken into account are the ones that are already available, no special recomputing is performed.
- See also:
- updateSizes
Definition at line 757 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_totalSize.
Referenced by Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst().
| 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().
| System::Size Ceylan::SmartResourceManager< Key >::getQuota | ( | ) | const [inline, virtual] |
Returns the smart resource manager current quota, in bytes.
- Note:
- A non-null quota does not imply resources can be dropped, the only criterion is the cache policy.
Definition at line 736 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_quota.
| bool Ceylan::SmartResourceManager< 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 965 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries.
Referenced by Ceylan::SmartResourceManager< Key >::scanForAddition().
| SmartResourceManager& Ceylan::SmartResourceManager< Key >::operator= | ( | const SmartResourceManager< 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.
| bool Ceylan::SmartResourceManager< Key >::scanForAddition | ( | const Key & | key, | |
| const SmartResource & | smartResource | |||
| ) | [inline, virtual] |
Puts, if possible, a clone of specified resource in cache, associated with specified key, without taking ownership of the specified resource.
With the 'NeverDrop' policy, the specified resource will be cloned and put in cache, provided the specified key is not already associated. If it was the case, then nothing would be done, the association would be left as it was.
With the 'DropLessRequestedFirst' policy, the smart Resource manager will do its best to add a clone of the resource in cache: if there is not enough space, the less requested resources already in cache will be dropped until the new smart resource clone can fit into the cache, provided it is simply possible, i.e. the resource size is smaller than the quota. Otherwise the resource will be trivially rejected and will not be cloned.
In all cases, the smart manager will handle on its own the life cycle of its clones, and will perform their deleting depending on the cache policy, but no later than its own deleting.
- Parameters:
-
key the key by which that resource should be retrieved. If this key is already associated with a resource, and, for the 'NeverDrop' policy, if the size of the new resource is smaller than the quota, the already cached resource is deallocated first, before being replaced by the new resource. smartResource the smart resource to put in cache. It may not be a dynamically allocated resource, since it will be either left alone or cloned, but never owned.
- Returns:
- true iff the specified resource could be cached. For example, if the size of the resource is higher than the manager quota, then the resource will not be stored and false will be directly returned.
Definition at line 773 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_policy, Ceylan::SmartResourceManager< Key >::_quota, Ceylan::SmartResourceManager< Key >::addEntry(), Ceylan::SmartResourceManager< Key >::applyPolicy(), Ceylan::Clonable::clone(), generalUtils::false, Ceylan::Measurable::getSizeInMemory(), Ceylan::SmartResourceManager< Key >::isKeyAlreadyAssociated(), Ceylan::SmartResourceManager< Key >::NeverDrop, and generalUtils::true.
| 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().
| bool Ceylan::SmartResourceManager< Key >::takeOwnershipOf | ( | const Key & | key, | |
| const SmartResource & | resource | |||
| ) | [inline, virtual] |
Puts specified resource in cache, associated with specified key, and takes ownership of it.
The Resource manager takes ownership of all the supplied resources and will perform their deleting whenever its current policy requests it, or during its own deleting, or when the 'flush' method is called.
If the policy is 'NeverDrop' and if the key is already associated to a resource, then the association is left as is, and a ResourceManagerException is raised.
- Parameters:
-
key the key by which that resource could be retrieved. If this key is already associated with a resource, and if the cache policy is 'NeverDrop', an exception is raised. Otherwise the preceding entry is dropped and the new resource replaces it. 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 appropriate.
- Returns:
- true iff the specified resource could be cached. Even though the resource could not be cached, the manager will deallocate it, so that the caller can rely on the fact that in all cases he has nothing to do with the submitted resource after this call. The caller notably must not delete the resource since the manager will always handle the deleting itself.
- Exceptions:
-
ResourceManagerException if the specified key was already associated with a Resource, and if the policy is 'NeverDrop'.
- See also:
- isKeyAlreadyAssociated
Definition at line 836 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_policy, Ceylan::SmartResourceManager< Key >::_quota, Ceylan::SmartResourceManager< Key >::addEntry(), Ceylan::SmartResourceManager< Key >::applyPolicy(), generalUtils::false, Ceylan::Measurable::getSizeInMemory(), Ceylan::SmartResourceManager< Key >::NeverDrop, and generalUtils::true.
| 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::SmartResourceManager< 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 1029 of file CeylanSmartResourceManager.h.
References Ceylan::ResourceManager< Key >::_cacheHits, Ceylan::ResourceManager< Key >::_cacheMisses, Ceylan::SmartResourceManager< Key >::_droppedByPolicy, Ceylan::SmartResourceManager< Key >::_entries, Ceylan::SmartResourceManager< Key >::_policy, Ceylan::SmartResourceManager< Key >::_quota, Ceylan::SmartResourceManager< Key >::_totalSize, Ceylan::SmartResourceManager< Key >::DropLessRequestedFirst, dataUtils::f, Ceylan::formatStringList(), Ceylan::low, Ceylan::medium, Ceylan::SmartResourceManager< Key >::NeverDrop, Ceylan::toNumericalString(), and Ceylan::toString().
| void Ceylan::SmartResourceManager< Key >::update | ( | ) | [inline, virtual] |
Updates the cache metadata: recomputes the size in memory of each cache entry, and applies the selected cache policy.
- See also:
- updateSizes, applyPolicy
Definition at line 921 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::applyPolicy(), and Ceylan::SmartResourceManager< Key >::updateSizes().
| void Ceylan::SmartResourceManager< Key >::updateSizes | ( | ) | [inline, virtual] |
Recomputes the size in memory of each cache entry.
Definition at line 932 of file CeylanSmartResourceManager.h.
References Ceylan::SmartResourceManager< Key >::_entries, and Ceylan::SmartResourceManager< Key >::_totalSize.
Referenced by Ceylan::SmartResourceManager< Key >::update().
Member Data Documentation
Ceylan::Uint32 Ceylan::ResourceManager< Key >::_cacheHits [protected, inherited] |
Records the total number of requested resources successfully found in cache.
Definition at line 229 of file CeylanResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::get(), Ceylan::BasicResourceManager< Key >::get(), Ceylan::SmartResourceManager< Key >::getClone(), Ceylan::SmartResourceManager< Key >::toString(), and Ceylan::BasicResourceManager< Key >::toString().
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::BasicResourceManager< Key >::get(), Ceylan::SmartResourceManager< Key >::toString(), and Ceylan::BasicResourceManager< Key >::toString().
Ceylan::Uint32 Ceylan::SmartResourceManager< Key >::_droppedByPolicy [protected] |
Records the total number of resources dropped by this manager because of cache policy (counting neither resource replacements because of key collision nor the final drops caused by manager deleting).
Definition at line 606 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::dropEntryDueToPolicy(), and Ceylan::SmartResourceManager< Key >::toString().
std::map<Key, CacheEntry *> Ceylan::SmartResourceManager< Key >::_entries [protected] |
Definition at line 646 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::addEntry(), Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst(), Ceylan::SmartResourceManager< Key >::dropEntry(), Ceylan::SmartResourceManager< Key >::flush(), Ceylan::SmartResourceManager< Key >::get(), Ceylan::SmartResourceManager< Key >::getClone(), Ceylan::SmartResourceManager< Key >::isKeyAlreadyAssociated(), Ceylan::SmartResourceManager< Key >::toString(), and Ceylan::SmartResourceManager< Key >::updateSizes().
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().
CachePolicy Ceylan::SmartResourceManager< Key >::_policy [protected] |
The policy enforced by this cache.
Definition at line 595 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::addEntry(), Ceylan::SmartResourceManager< Key >::applyPolicy(), Ceylan::SmartResourceManager< Key >::getCachePolicy(), Ceylan::SmartResourceManager< Key >::scanForAddition(), Ceylan::SmartResourceManager< Key >::takeOwnershipOf(), and Ceylan::SmartResourceManager< Key >::toString().
System::Size Ceylan::SmartResourceManager< Key >::_quota [protected] |
The quota that would be enforced by this cache, provided that a policy makes us of it.
Definition at line 580 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::applyDropLessRequestedFirst(), Ceylan::SmartResourceManager< Key >::getQuota(), Ceylan::SmartResourceManager< Key >::scanForAddition(), Ceylan::SmartResourceManager< Key >::takeOwnershipOf(), and Ceylan::SmartResourceManager< Key >::toString().
System::Size Ceylan::SmartResourceManager< Key >::_totalSize [protected] |
The approximate total size of all cached resources, as computed after last resource inspection and updated on drop/put operations.
Definition at line 590 of file CeylanSmartResourceManager.h.
Referenced by Ceylan::SmartResourceManager< Key >::addEntry(), Ceylan::SmartResourceManager< Key >::dropEntry(), Ceylan::SmartResourceManager< Key >::flush(), Ceylan::SmartResourceManager< Key >::getFootprint(), Ceylan::SmartResourceManager< Key >::toString(), and Ceylan::SmartResourceManager< Key >::updateSizes().
The documentation for this class was generated from the following file:
