vrecko
virtual reality framework
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
vrecko::PersistentCache Class Reference

Caching that persists multiple application sessions. More...

#include <PersistentCache.h>

Classes

class  OpenedCacheFile
 

Public Member Functions

 PersistentCache ()
 
 ~PersistentCache ()
 
void setEnable (bool bNewEnableCache)
 
bool getEnable ()
 
const char * getCacheDir ()
 
osg::Node * loadModel (const char *relatedFileName, vrecko::EnvironmentObject *obj)
 
bool saveModel (const char *relatedFileName, osg::Node *node, vrecko::EnvironmentObject *obj)
 
bool openCacheFileForReading (const char *dataName, const char *relatedFileName, unsigned long version, OpenedCacheFile **cacheData, vrecko::BufferedFile **bfile, unsigned long ulWaitTimeout=0)
 
void closeCacheFile (OpenedCacheFile *cacheData, vrecko::BufferedFile *bfile)
 
bool openCacheFileForWriting (const char *dataName, const char *relatedFileName, unsigned long version, OpenedCacheFile **cacheData, vrecko::BufferedFileWrite **bfile, unsigned long ulWaitTimeout=0)
 
void closeCacheFile (OpenedCacheFile *cacheData, vrecko::BufferedFileWrite *bfile)
 

Protected Member Functions

void translateName (char *outTranslatedName, const char *inDataName, const char *inRelatedFileName)
 
int internalFindAndLock (const char *originalFileName, const char *translatedFileName, unsigned long version, const char *desiredExtension, bool bReading, unsigned long ulWaitTimeout)
 
bool internalOpenReadWrite (const char *dataName, const char *relatedFileName, unsigned long version, OpenedCacheFile **cacheData, vrecko::BufferedFile **bfile, vrecko::BufferedFileWrite **bfileWrite, unsigned long ulWaitTimeout)
 
void internalDecrementReaderWriter (OpenedCacheFile *cacheData, bool bReading)
 
bool testVersionIsAtLeast (const char *fileName, int minVersion)
 
void constructModelDataName (char *outDataName, vrecko::EnvironmentObject *obj)
 

Protected Attributes

bool bEnableCache
 
DynamicArray< OpenedCacheFile * > openedFiles
 
MTLock filesLock
 
CHAR baseDir [1000]
 
CHAR cacheDir [1000]
 

Detailed Description

Caching that persists multiple application sessions.

Persistent cache with data saving into files (into the "cache" directory). The class is multithread safe, multiple threads can read from the same file. Only one writer can write into a file - readers will be blocked and everything should be correctly managed automatically, i.e. from the time the writer requests writing, the next requesting readers will be blocked and remaining readers will finish their reading. Then the writer will be allowed to write (all this happen if the [Timeout] is sufficient).

IDEAS: 0. Most of the data are related to files - i.e. we will check whether the specific file hasn't changed.

  1. Two different names for data (data taken from a file):
  • the first is the ORIGINAL file name or data name (might be for example "..\data\model.obj")
  • the second is the name of cached object, with some characters translated into safer ones and with the added timestamp (i.e. "~~$data$model~obj$2009.12.20.19.44.20.dat")

This second name is composed of [the translated original file name] + [data name] + [timestamp] + [extension]

Author
Vit Kovalcik
Date
2011

Constructor & Destructor Documentation

vrecko::PersistentCache::PersistentCache ( )
vrecko::PersistentCache::~PersistentCache ( )

Member Function Documentation

void vrecko::PersistentCache::closeCacheFile ( OpenedCacheFile *  cacheData,
vrecko::BufferedFile *  bfile 
)

The [cacheData] + [bfile] structures will be NO LONGER VALID after calling this method.

void vrecko::PersistentCache::closeCacheFile ( OpenedCacheFile *  cacheData,
vrecko::BufferedFileWrite *  bfile 
)

The [cacheData] + [bfile] structures will be NO LONGER VALID after calling this method.

void vrecko::PersistentCache::constructModelDataName ( char *  outDataName,
vrecko::EnvironmentObject *  obj 
)
protected

Used mainly in the loadModel() and saveModel() methods. The [obj] is necessary for getting attributes related to the model, i.e. Is it optimized? Is it smoothed? etc. - all produces different cache file The [obj] might be NULL in which case the default parameters are used.

const char* vrecko::PersistentCache::getCacheDir ( )
inline
bool vrecko::PersistentCache::getEnable ( )
inline

Is caching enabled?

void vrecko::PersistentCache::internalDecrementReaderWriter ( OpenedCacheFile *  cacheData,
bool  bReading 
)
protected

Effectively UNLOCK a FILE for reading/writing. The [cacheData] MIGHT BE INVALID after calling this method. It might get deleted if noone else uses that file. The real file should be close BEFORE calling this method.

int vrecko::PersistentCache::internalFindAndLock ( const char *  originalFileName,
const char *  translatedFileName,
unsigned long  version,
const char *  desiredExtension,
bool  bReading,
unsigned long  ulWaitTimeout 
)
protected

Note: The function will acquire the [filesLock] itself. This function will find correct entry in [openedFiles] OR will create a new one if it doesn't exist. If the entry exist, the function will check if the file itself is readable/writable and in case it is not it will wait for [ulWaitTimeout] ms (may be also 0 or INFINITE). Result is a 0 or positive number (if the entry was found/created) and the file can be processed, or -1 in case of blockage. If the result is 0 or positive number, the [filesLock] will REMAIN LOCKED AT THE END OF THIS FUNCTION. The function employs a busy-waiting (with 1 milisecond Sleep() ). The [ulWaitTimeout] is probably only approximate and not a precise number. The [desiredExtension] is used only if writing.

bool vrecko::PersistentCache::internalOpenReadWrite ( const char *  dataName,
const char *  relatedFileName,
unsigned long  version,
OpenedCacheFile **  cacheData,
vrecko::BufferedFile **  bfile,
vrecko::BufferedFileWrite **  bfileWrite,
unsigned long  ulWaitTimeout 
)
protected
osg::Node * vrecko::PersistentCache::loadModel ( const char *  relatedFileName,
vrecko::EnvironmentObject *  obj 
)

The [obj] is necessary for getting attributes related to the model, i.e. Is it optimized? Is it smoothed? etc. - all produces different cache file The [obj] might be NULL in which case the default parameters are used.

bool vrecko::PersistentCache::openCacheFileForReading ( const char *  dataName,
const char *  relatedFileName,
unsigned long  version,
OpenedCacheFile **  cacheData,
vrecko::BufferedFile **  bfile,
unsigned long  ulWaitTimeout = 0 
)
inline

NOTE: [version] = 0 is NOT RECOMMENDED In case of success the [bfile] will hold a pointer to the existing file opened for reading and [cacheData] will hold proper structure which acts as a handle. Note: [ulWaitTimeout] can be INFINITE (= Windows' numeric constant). The [cacheData] may be NULL.

bool vrecko::PersistentCache::openCacheFileForWriting ( const char *  dataName,
const char *  relatedFileName,
unsigned long  version,
OpenedCacheFile **  cacheData,
vrecko::BufferedFileWrite **  bfile,
unsigned long  ulWaitTimeout = 0 
)
inline

NOTE: [version] = 0 is NOT RECOMMENDED In case of success the [bfile] will hold a pointer to the new empty file opened for writing and [cacheData] will hold proper structure which acts as a handle. Note: [ulWaitTimeout] can be INFINITE (= Windows' numeric constant).

bool vrecko::PersistentCache::saveModel ( const char *  relatedFileName,
osg::Node *  node,
vrecko::EnvironmentObject *  obj 
)

The [obj] is necessary for getting attributes related to the model, i.e. Is it optimized? Is it smoothed? etc. - all produces different cache file The [obj] might be NULL in which case the default parameters are used.

void vrecko::PersistentCache::setEnable ( bool  bNewEnableCache)

Can be used to disable and enable the whole caching system.

bool vrecko::PersistentCache::testVersionIsAtLeast ( const char *  fileName,
int  minVersion 
)
protected

Test whether the file name contains version at the end (returning "false" if not) and the version is at least [minVersion].

void vrecko::PersistentCache::translateName ( char *  outTranslatedName,
const char *  inDataName,
const char *  inRelatedFileName 
)
protected

Translates original file name into the safe name ending with '$', the date part and the final extension of the resulting file will be missing. The file path will be translated into a path relative to the main vrecko directory.

Member Data Documentation

CHAR vrecko::PersistentCache::baseDir[1000]
protected

Main program directory. Ending with backslash.

bool vrecko::PersistentCache::bEnableCache
protected
CHAR vrecko::PersistentCache::cacheDir[1000]
protected

Cache directory. Ending with backslash.

MTLock vrecko::PersistentCache::filesLock
protected

Lock for access to the [openedFiles] structure. ( It doesn't block (accesses to multiple files at once) or (multiple read accesses to a single file)

DynamicArray<OpenedCacheFile*> vrecko::PersistentCache::openedFiles
protected

MUST be array of pointers and NOT array of structures -> we will send these pointers as parameters and this would be screwed if the array was reallocated.

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