King_DuckZ/Loki
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Added Doxygen documentation

Browse source 
git-svn-id: svn://svn.code.sf.net/p/loki-lib/code/trunk@767 7ec92016-0320-0410-acc4-a06ded1c099a
This commit is contained in:
clitte_bbt 2006-10-22 22:28:24 +00:00
parent 37f2743043
commit 07d6c5d61f
1 changed files with 155 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

237
include/loki/CachedFactory.h
View file

@ -51,19 +51,34 @@ using std::bind2nd;
using std::equal_to; using std::equal_to;
using std::cout; using std::cout;
using std::endl; using std::endl;
/**
* \defgroup FactoryGroup Factory
* \defgroup CachedFactoryGroup Cached Factory
* \ingroup FactoryGroup
* \brief CachedFactory provides an extension of a Factory with caching
* support.
*
* Once used objects are returned to the CachedFactory that manages its
* destruction.
* If your code uses lots of "long to construct/destruct objects" using the
* CachedFactory will surely speedup the execution.
*/
namespace Loki namespace Loki
{ {
/////////////////////////////////////////////////////////////////////////// /**
// Encapsulation Policy * \defgroup EncapsulationPolicyCachedFactoryGroup Encapsulation policies
// Defines how the object is returned to the client * \ingroup CachedFactoryGroup
/////////////////////////////////////////////////////////////////////////// * \brief Defines how the object is returned to the client
*/
/* /**
* Encapsulation Policy : SimplePointer * \class SimplePointer
* this implementation does not make any encapsulation * \ingroup EncapsulationPolicyCachedFactoryGroup
* It simply returns the object's pointer * \brief No encaspulation : returns the pointer
*/ *
* This implementation does not make any encapsulation.
* It simply returns the object's pointer.
*/
template<class AbstractProduct> template<class AbstractProduct>
class SimplePointer class SimplePointer
{ {
@ -82,21 +97,25 @@ namespace Loki
} }
const char* name(){return "pointer";} const char* name(){return "pointer";}
}; };
///////////////////////////////////////////////////////////////////////////
// Creation Policy
// Defines a mean to limit the creation operation
// For instance one may want to be alerted (Exception) when
// + Cache has created a more than X object within the last x seconds
// + Cache creation rate has increased dramatically
// which may result from bad caching strategy, or critical overload
///////////////////////////////////////////////////////////////////////////
/* /**
* Creation Policy : NeverCreate * \defgroup CreationPolicyCachedFactoryGroup Creation policies
* this implementation never allows creation * \ingroup CachedFactoryGroup
* !! TESTING PURPOSE ONLY !! * \brief Defines a way to limit the creation operation.
*/ *
* For instance one may want to be alerted (Exception) when
* - Cache has created a more than X object within the last x seconds
* - Cache creation rate has increased dramatically
* .
* which may result from bad caching strategy, or critical overload
*/
/**
* \class NeverCreate
* \ingroup CreationPolicyCachedFactoryGroup
* \brief Never allows creation. Testing purposes only.
*
* Using this policy will throw an exception.
*/
class NeverCreate class NeverCreate
{ {
protected: protected:
@ -115,10 +134,13 @@ namespace Loki
const char* name(){return "never";} const char* name(){return "never";}
}; };
/* /**
* Creation Policy : AlwaysCreate * \class AlwaysCreate
* this implementation always allows creation * \ingroup CreationPolicyCachedFactoryGroup
*/ * \brief Always allows creation.
*
* Doesn't limit the creation in any way
*/
class AlwaysCreate class AlwaysCreate
{ {
protected: protected:
@ -132,15 +154,17 @@ namespace Loki
const char* name(){return "always";} const char* name(){return "always";}
}; };
/*
* Creation Policy : RateLimitedCreation /**
* \class RateLimitedCreation
* \ingroup CreationPolicyCachedFactoryGroup
* \brief Limit in rate.
*
* This implementation will prevent from Creating more than maxCreation objects * This implementation will prevent from Creating more than maxCreation objects
* within byTime ms by throwing an exception. * within byTime ms by throwing an exception.
* * Could be usefull to detect prevent loads (http connection for instance).
* Could be usefull to detect heavy loads (http connection for instance) * Use the setRate method to set the rate parameters.
* * default is 10 objects in a second.
* Use the setRate method to set the rate parameters
* default is 10 objects in a second
*/ */
class RateLimitedCreation class RateLimitedCreation
{ {
@ -221,13 +245,15 @@ namespace Loki
} }
}; };
/* /**
* Creation Policy : AmountLimitedCreation * \class AmountLimitedCreation
* \ingroup CreationPolicyCachedFactoryGroup
* \brief Limit by number of objects
*
* This implementation will prevent from Creating more than maxCreation objects * This implementation will prevent from Creating more than maxCreation objects
* within byTime ms by calling eviction policy. * within byTime ms by calling eviction policy.
* * Use the setRate method to set the rate parameters.
* Use the setRate method to set the rate parameters * default is 10 objects.
* default is 10 objects
*/ */
class AmountLimitedCreation class AmountLimitedCreation
{ {
@ -267,12 +293,13 @@ namespace Loki
} }
}; };
/////////////////////////////////////////////////////////////////////////// /**
// Eviction Policy * \defgroup EvictionPolicyCachedFactoryGroup Eviction policies
// * \ingroup CachedFactoryGroup
// The eviction policy gathers information about the stored objects * \brief Gathers informations about the stored objects and choose a
// and choose a candidate for eviction * candidate for eviction.
/////////////////////////////////////////////////////////////////////////// */
class EvictionException : public std::exception class EvictionException : public std::exception
{ {
public: public:
@ -310,14 +337,18 @@ namespace Loki
} }
}; };
/////////////////////////////////////////////////////////////////////////// /**
// Least Recently Used Eviction Policy * \class EvictLRU
/////////////////////////////////////////////////////////////////////////// * \ingroup EvictionPolicyCachedFactoryGroup
// --> Evicts least accessed objects first * \brief Evicts least accessed objects first.
// If an object is heavily fetched *
// (more than ULONG_MAX = UINT_MAX = 4294967295U) * Implementation of the Least recent used algorithm as
// it could unfortunately be removed from the cache * described in http://en.wikipedia.org/wiki/Page_replacement_algorithms .
// *
* WARNING : If an object is heavily fetched
* (more than ULONG_MAX = UINT_MAX = 4294967295U)
* it could unfortunately be removed from the cache.
*/
template template
< <
typename DT, // Data Type (AbstractProduct*) typename DT, // Data Type (AbstractProduct*)
@ -366,11 +397,17 @@ namespace Loki
const char* name(){return "LRU";} const char* name(){return "LRU";}
}; };
/////////////////////////////////////////////////////////////////////////// /**
// Aging Eviction Policy * \class EvictAging
/////////////////////////////////////////////////////////////////////////// * \ingroup EvictionPolicyCachedFactoryGroup
// --> LRU aware of the time span of use * \brief LRU aware of the time span of use
// *
* Implementation of the Aging algorithm as
* described in http://en.wikipedia.org/wiki/Page_replacement_algorithms .
*
* This method is much more costly than evict LRU so
* if you need extreme performance consider switching to EvictLRU
*/
template template
< <
typename DT, // Data Type (AbstractProduct*) typename DT, // Data Type (AbstractProduct*)
@ -426,11 +463,14 @@ namespace Loki
const char* name(){return "LRU with aging";} const char* name(){return "LRU with aging";}
}; };
/////////////////////////////////////////////////////////////////////////// /**
// Random Eviction Policy * \class EvictRandom
/////////////////////////////////////////////////////////////////////////// * \ingroup EvictionPolicyCachedFactoryGroup
// --> Evicts a random object * \brief Evicts a random object
// *
* Implementation of the Random algorithm as
* described in http://en.wikipedia.org/wiki/Page_replacement_algorithms .
*/
template template
< <
typename DT, // Data Type (AbstractProduct*) typename DT, // Data Type (AbstractProduct*)
@ -477,11 +517,22 @@ namespace Loki
const char* name(){return "random";} const char* name(){return "random";}
}; };
/////////////////////////////////////////////////////////////////////////// /**
// Statistic Policy * \defgroup StatisticPolicyCachedFactoryGroup Statistic policies
// Statistic Policy is used provide informations about the Caching efficiency * \ingroup CachedFactoryGroup
/////////////////////////////////////////////////////////////////////////// * \brief Gathers information about the cache.
*
* For debugging purpose this policy proposes to gather informations
* about the cache. This could be useful to determine whether the cache is
* mandatory or if the policies are well suited to the application.
*/
/**
* \class NoStatisticPolicy
* \ingroup StatisticPolicyCachedFactoryGroup
* \brief Do nothing
*
* Should be used in release code for better performances
*/
class NoStatisticPolicy class NoStatisticPolicy
{ {
protected: protected:
@ -493,6 +544,21 @@ namespace Loki
const char* name(){return "no";} const char* name(){return "no";}
}; };
/**
* \class SimpleStatisticPolicy
* \ingroup StatisticPolicyCachedFactoryGroup
* \brief Simple statistics
*
* Provides the following informations about the cache :
* - Created objects
* - Fetched objects
* - Destroyed objects
* - Cache hit
* - Cache miss
* - Currently allocated
* - Currently out
* - Cache overall efficiency
*/
class SimpleStatisticPolicy class SimpleStatisticPolicy
{ {
private: private:
@ -561,14 +627,17 @@ namespace Loki
public: public:
const char* what() const throw() { return "Internal Cache Error"; } const char* what() const throw() { return "Internal Cache Error"; }
}; };
/** /**
* CachedFactory implementation * \class CachedFactory
* This class acts as a Factory (it creates objects) * \ingroup FactoryGroup
* but also keeps the already created objects to prevent * \brief Factory with caching support
* long constructions time *
* * This class acts as a Factory (it creates objects)
* This implementation do not retain ownership * but also keeps the already created objects to prevent
* long constructions time.
*
* Note this implementation do not retain ownership.
*/ */
template template
< <
@ -614,7 +683,6 @@ namespace Loki
typedef typename NP::ProductReturn ProductReturn; typedef typename NP::ProductReturn ProductReturn;
typedef Key< Impl, IdentifierType > Key; typedef Key< Impl, IdentifierType > Key;
//typedef typename Vector ObjVector;
typedef std::map< Key, ObjVector > KeyToObjVectorMap; typedef std::map< Key, ObjVector > KeyToObjVectorMap;
typedef std::map< AbstractProduct*, Key > FetchedObjToKeyMap; typedef std::map< AbstractProduct*, Key > FetchedObjToKeyMap;
@ -718,7 +786,7 @@ namespace Loki
CachedFactory() : factory(), fromKeyToObjVector(), providedObjects(), outObjects(0) CachedFactory() : factory(), fromKeyToObjVector(), providedObjects(), outObjects(0)
{ {
} }
~CachedFactory() ~CachedFactory()
{ {
SP::onDebug(); SP::onDebug();
@ -758,6 +826,7 @@ namespace Loki
} }
// TODO : prevent the Vector to be returned by copy. // TODO : prevent the Vector to be returned by copy.
/// Return the registered ID in this Factory
std::vector<IdentifierType> RegisteredIds() std::vector<IdentifierType> RegisteredIds()
{ {
return factory.RegisteredIds(); return factory.RegisteredIds();
@ -1032,13 +1101,16 @@ namespace Loki
return NP::encapsulate(pProduct); return NP::encapsulate(pProduct);
} }
/// Use this function to release the object
/**
* if execution brakes ni this function then you tried
* to release an object that wasn't provided by this Cache
* ... which is bad :-)
*/
void ReleaseObject(ProductReturn &object) void ReleaseObject(ProductReturn &object)
{ {
AbstractProduct* pProduct(NP::release(object)); AbstractProduct* pProduct(NP::release(object));
typename FetchedObjToKeyMap::iterator itr = providedObjects.find(pProduct); typename FetchedObjToKeyMap::iterator itr = providedObjects.find(pProduct);
// if execution brakes on the following lines then you tried
// to release an object that wasn't provided by this Cache
// ... which is bad :-)
if(itr == providedObjects.end()) if(itr == providedObjects.end())
throw CacheException(); throw CacheException();
onRelease(pProduct); onRelease(pProduct);
@ -1046,6 +1118,7 @@ namespace Loki
providedObjects.erase(itr); providedObjects.erase(itr);
} }
/// display the cache configuration
void displayCacheType() void displayCacheType()
{ {
cout << "############################" << endl; cout << "############################" << endl;