gcgCACHE Class Reference

Defines a synchronized and thread safe memory cache. This is an abstract data structure that may be used to restrict the existence of multiple objects at a time in memory. This class manages key/value pairs using a TRIE tree and a double linked list. The key is generally, a short and unique identity for the data which, in turn, can be of any size. In fact, gcgCACHE stores only the pointer to the data regardless the memory chunk it spans. A key in gcgCACHE can have up to 255 bytes, or be a null terminated string, and all methods access it by a pointer. If the key has at most sizeof(long), the underlying data structure will work more efficiently due to specific optimizations. The size in bytes of the key is configured with setKeySize() method. If zero is given, the keys are treated as null terminated strings with a maximum length of 254. Note that the keys are stored internally for each key/value pair. There are two main interfaces: one for the application requests (non-virtual and data independent methods) and one for the data creation, removal and persistence (abstract, virtual and data dependent methods that must be implemented). The main application interface consists of the get() method for which the application presents the desired key and, if the corresponding data is cached (cache hit), it returns its pointer immediately (its entry is marked as the most recently used). If the data is not present (cache miss), the data interface is called for its retrieval before get() returns. In this case, the gcgCLASS calls the retrieveData() method to get the missing data for the requested key. If the missing data is retrieved but the cache is full (the cache cost capacity exceeds with the new key/value cost), the gcgCACHE calls the discardData() to delete or persist the least recently used key/value pairs until the cost of the new key/value fits in the cache limit. At any time, the application can discard one or all entries by calling flush() method. More...

#include <gcg.h>

Inheritance diagram for gcgCACHE:

Public Member Functions
	gcgCACHE (unsigned int keysizebytes, unsigned long cachecapacity)
	Constructs an empty cache. More...
virtual	~gcgCACHE ()
	Destroys the cache. If the cache total cost is non-zero, then flush(NULL) is called to release all key/value pairs and cache resources. More...
void *	get (void *key)
	Gets the data corresponding to the key and mark its internal entry as the most recently used. If the data associated with the key is not stored in the cache (cache miss), the retrieveData() method is called to get the missing data for the requested key. If the missing data is retrieved but the cache is full (the cache cost capacity exceeds with the new key/value cost), the discardData() method is called to delete or persist the least recently used key/value pairs until the cost of the new key/value fits in the cache limit. Both key and data contents and interpretation are application dependent and must be fully resolved by the data interface. If the cache is empty, this method allocates all needed resources. Thus, the cache capacity (see setCapacity()) and the key size in bytes must be defined before the first get() call. More...
bool	flush (void *key)
	Discard and remove the entry of a specific key/value pair, or all key/value stored in the cache. Before internal removal, the discardData() method is called for each pair in order to be deleted and/or persisted by the data interface. The total cost summation of the cache is reduced accordingly. If the flush(NULL) is called, all key/value are discarded and the cache resources are released. More...
bool	setCapacity (unsigned long maximumtotalcost)
	Sets the capacity of the cache, i.e. the maximum allowed value for the sum of costs of all key/value pairs. If the current total cost is greater than the new capacity, the least recently used key/value pairs are flushed until the sum of costs becomes smaller or equal to the new capacity. The cost unit can be anything: bytes, number of elements, area, weight, etc. It is application dependent and only concerns the data interface. If maximumtotalcost is zero, all key/value are discarded and the cache resources are released. More...
bool	setKeySize (unsigned int keysizebytes)
	Sets the size, in bytes, of the key. This operation is only possible if the cache is empty, i.e. there is no key/value stored. The maximum allowed key size is 255. If zero (default value), the keys are null terminated strings. The key size is important for the cache performance. Best performance is achieved with at most sizeof(long) bytes. More...
virtual void *	retrieveData (void *key, unsigned long *datacost)=0
	Invoked by the gcgCACHE to fulfill a request that resulted in a cache miss when get() was called. Given the key, this method must provide its associated data and its cost. If this is not possible, it must return NULL to tell get() to also return NULL to the application. If the data cost is greater than the cache capacity, the get() will subsequently discard it by calling discardData(). More...
virtual void	discardData (void *key, void *data, unsigned long datacost)=0
	Invoked by the gcgCACHE to discard a key/value pair. It must release and/or save the key/pair resources because gcgCACHE will erase any internal reference to it. It is called by the flush() method, when the application need to delete and/or persist a pair, or by the get() method, to reduce the current total cost in response to a cache miss. The cache total cost is updated after the call to discardData(). This method is synchronized which means that the cache is locked while discardData() is executed. More...
Public Member Functions inherited from gcgCLASS
void *	operator new (size_t size)
	Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More...
void *	operator new (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More...
void *	operator new[] (size_t size)
	Defines a new operator to be used by GCGlib array allocations instead the global one. More...
void *	operator new[] (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by vector allocations instead the global one. More...
void	operator delete (void *p)
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...
void	operator delete (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...
void	operator delete[] (void *p)
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...
void	operator delete[] (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

Public Attributes
unsigned long	totalcost
	Sum of the cost of all key/value pairs. Read-Only.
unsigned long	capacity
	Maximum sum of data costs this cache supports. Read-Only. See setMaximumCost().
unsigned int	keysize
	Size of each key in bytes. If zero, the key is a null terminated string. Maximum value is 255. Read-Only. See setKeySize().

Private Attributes
void *	handle
	Internal handle of this object.

Detailed Description

Defines a synchronized and thread safe memory cache. This is an abstract data structure that may be used to restrict the existence of multiple objects at a time in memory. This class manages key/value pairs using a TRIE tree and a double linked list. The key is generally, a short and unique identity for the data which, in turn, can be of any size. In fact, gcgCACHE stores only the pointer to the data regardless the memory chunk it spans. A key in gcgCACHE can have up to 255 bytes, or be a null terminated string, and all methods access it by a pointer. If the key has at most sizeof(long), the underlying data structure will work more efficiently due to specific optimizations. The size in bytes of the key is configured with setKeySize() method. If zero is given, the keys are treated as null terminated strings with a maximum length of 254. Note that the keys are stored internally for each key/value pair. There are two main interfaces: one for the application requests (non-virtual and data independent methods) and one for the data creation, removal and persistence (abstract, virtual and data dependent methods that must be implemented). The main application interface consists of the get() method for which the application presents the desired key and, if the corresponding data is cached (cache hit), it returns its pointer immediately (its entry is marked as the most recently used). If the data is not present (cache miss), the data interface is called for its retrieval before get() returns. In this case, the gcgCLASS calls the retrieveData() method to get the missing data for the requested key. If the missing data is retrieved but the cache is full (the cache cost capacity exceeds with the new key/value cost), the gcgCACHE calls the discardData() to delete or persist the least recently used key/value pairs until the cost of the new key/value fits in the cache limit. At any time, the application can discard one or all entries by calling flush() method.

Since

0.02.113

Constructor & Destructor Documentation

gcgCACHE()

gcgCACHE::gcgCACHE	(	unsigned int	keysizebytes,
		unsigned long	cachecapacity
	)

Constructs an empty cache.

Parameters

[in]	keysizebytes	size of the key in bytes. If zero, the keys are considered null terminated strings. If greater than 255, it is truncated to 255. The key size is important for the cache performance. Best performance is achieved with at most sizeof(long) bytes.
[in]	cachecapacity	maximum sum of all costs that this cache supports. A zero value will prevent the cache of being used until setCapacity() is called and will issue a warning. The cost unit can be anything: bytes, number of elements, area, weight, etc. It is application dependent and only concerns the data interface.

See also

setCapacity()

setKeySize()

get()

~gcgCACHE()

virtual gcgCACHE::~gcgCACHE ( )

virtual

Destroys the cache. If the cache total cost is non-zero, then flush(NULL) is called to release all key/value pairs and cache resources.

See also

flush()

Member Function Documentation

discardData()

virtual void gcgCACHE::discardData ( void *  key, void *  data, unsigned long  datacost  )

pure virtual

Invoked by the gcgCACHE to discard a key/value pair. It must release and/or save the key/pair resources because gcgCACHE will erase any internal reference to it. It is called by the flush() method, when the application need to delete and/or persist a pair, or by the get() method, to reduce the current total cost in response to a cache miss. The cache total cost is updated after the call to discardData(). This method is synchronized which means that the cache is locked while discardData() is executed.

Parameters

[in]	key	pointer of a sequence of bytes representing the key of the data to be discarded or persisted.
[in]	data	pointer to the data that must be discarded or persisted.
[in]	datacost	cost of the data being discarded or persisted.

See also

get()

flush()

retrieveData()

flush()

bool gcgCACHE::flush

(

void *

key

)

Discard and remove the entry of a specific key/value pair, or all key/value stored in the cache. Before internal removal, the discardData() method is called for each pair in order to be deleted and/or persisted by the data interface. The total cost summation of the cache is reduced accordingly. If the flush(NULL) is called, all key/value are discarded and the cache resources are released.

Parameters

[in]

key

pointer to a sequence of bytes representing the key of the data to be flushed.

Returns

true if the key/value was found and successfully discarded. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

get()

discardData()

get()

void* gcgCACHE::get

(

void *

key

)

Gets the data corresponding to the key and mark its internal entry as the most recently used. If the data associated with the key is not stored in the cache (cache miss), the retrieveData() method is called to get the missing data for the requested key. If the missing data is retrieved but the cache is full (the cache cost capacity exceeds with the new key/value cost), the discardData() method is called to delete or persist the least recently used key/value pairs until the cost of the new key/value fits in the cache limit. Both key and data contents and interpretation are application dependent and must be fully resolved by the data interface. If the cache is empty, this method allocates all needed resources. Thus, the cache capacity (see setCapacity()) and the key size in bytes must be defined before the first get() call.

Parameters

[in]

key

pointer to a sequence of bytes representing the key of the requested data. It must point to a block having at least the expected key size which was set up with setKeySize(). If the key size is zero, the pointer must point to a null terminated char string.

Returns

the pointer to the data associated with the key. If the data is not cached and could not be retrieved by the data interface, or its cost is greater than the cache capacity, it returns NULL. Check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

setCapacity()

flush()

retrieveData()

setKeySize()

retrieveData()

virtual void* gcgCACHE::retrieveData ( void *  key, unsigned long *  datacost  )

pure virtual

Invoked by the gcgCACHE to fulfill a request that resulted in a cache miss when get() was called. Given the key, this method must provide its associated data and its cost. If this is not possible, it must return NULL to tell get() to also return NULL to the application. If the data cost is greater than the cache capacity, the get() will subsequently discard it by calling discardData().

Parameters

[in]	key	pointer of a sequence of bytes representing the key of the requested data.
[out]	datacost	pointer to an unsigned long that must receive the cost of the requested key/value pair. If this cost is greater that the cache capacity, the get() will subsequently discard the pair by calling discardData(). This method is synchronized which means that the cache is locked while retrieveData() is executed.

Returns

it must return a pointer to the data associated to the key. If the key is invalid or the data is not available, it must return NULL to tell get() to also return NULL to the application. gcgCACHE does not copy the data and the application is fully responsible for data allocation and deallocation.

See also

get()

flush()

discardData()

setCapacity()

bool gcgCACHE::setCapacity

(

unsigned long

maximumtotalcost

)

Sets the capacity of the cache, i.e. the maximum allowed value for the sum of costs of all key/value pairs. If the current total cost is greater than the new capacity, the least recently used key/value pairs are flushed until the sum of costs becomes smaller or equal to the new capacity. The cost unit can be anything: bytes, number of elements, area, weight, etc. It is application dependent and only concerns the data interface. If maximumtotalcost is zero, all key/value are discarded and the cache resources are released.

Parameters

[in]

maximumtotalcost

maximum sum of all costs that this cache supports. If it is zero, all key/value are discarded and it will prevent cache accesses until setCapacity() is called with a non-zero value.

Returns

true if the capacity was successfully set and the cache is consistent, i.e. the sum of costs is less than or equal to the new capacity. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also

get()

flush()

discardData()

setKeySize()

bool gcgCACHE::setKeySize

(

unsigned int

keysizebytes

)

Sets the size, in bytes, of the key. This operation is only possible if the cache is empty, i.e. there is no key/value stored. The maximum allowed key size is 255. If zero (default value), the keys are null terminated strings. The key size is important for the cache performance. Best performance is achieved with at most sizeof(long) bytes.

Parameters

[in]

keysizebytes

size of the key in bytes. If zero, the keys are null terminated strings. If greater than 255, it is truncated to 255.

Returns

true if the key size was successfully set up. It returns false if there are key/pairs stored, and keysizebytes is different than the current key size.

See also

get()

---

The documentation for this class was generated from the following file:

• M:/Documentos/Projetos/Projetos/GCGlib/src/gcg.h