Abstract base class of file data cache implementations. More...

#include <FileDataCache.h>

Public Member Functions
	FileDataCache (const IsoString &identifier, int maxItemDuration=30)

virtual	~FileDataCache ()

void	Add (const FileDataCacheItem &item)

virtual String	CacheName () const

void	Clear ()

void	DisableCompression (bool disable=true)

void	EnableCompression (bool enable=true)

fsize_type	FileSize () const

const FileDataCacheItem *	Find (const String &path, const IsoString &key=IsoString()) const

bool	Get (FileDataCacheItem &item, const String &path, const IsoString &key=IsoString())

bool	IsCompressionEnabled () const

bool	IsEmpty () const

bool	IsModified () const

bool	ItemsNeverExpire () const

virtual void	Load ()

int	MaxItemDuration () const

virtual int	MinSupportedVersion () const

int	ModifiedCount () const

size_type	NumberOfItems () const

virtual void	Purge () const

virtual void	Save () const

virtual void	SetMaxItemDuration (int days)

void	SetTokenSeparator (const IsoString &separator)

IsoString	TokenSeparator () const

virtual int	Version () const

Protected Member Functions
virtual FileDataCacheItem *	NewItem () const =0

Detailed Description

This class provides the necessary infrastructure to implement a specialized file cache with persistent storage in special cache files.

The main cache access functions provided by this class to add, get and find cache items, as well as to clear the cache and query cache properties, are implemented as thread-safe routines. This supports applications performing parallel disk I/O operations and multiple application instances running concurrently, with separate per-instance cache data files.

Cache files are generated and managed transparently on platform-dependent configuration directories.

You'll find examples of use for this class in standard PixInsight modules such as ImageIntegration and SubframeSelector.

See also: FileDataCacheItem

Definition at line 294 of file FileDataCache.h.

Constructor & Destructor Documentation

◆ FileDataCache()

pcl::FileDataCache::FileDataCache	(	const IsoString &	identifier,
		int	maxItemDuration = `30`
	)

Constructs a new file data cache structure.

Parameters

identifier	A valid identifier (see IsoString::IsValidIdentifier()) that will be used to construct the unique name of a special cache data file where all cache data structures associated with this object will be stored persistently for the running core application instance.
maxItemDuration	The maximum duration in days for valid cache items. The supported range is from zero (meaning that cache items never expire) to 120 days. The default value is 30 days.

Warning: If the specified value of maxItemDuration is ≤ 0, existing cache items will never expire. This is not recommended and can cause problems by increasing the size of cache files indiscriminately. In general, the default maximum duration of 30 days is quite appropriate for most applications.

◆ ~FileDataCache()

virtual pcl::FileDataCache::~FileDataCache ( )

inlinevirtual

Virtual destructor.

Destroys and deallocates all file data cache items and internal structures associated with this object. Note that this refers to data currently stored in memory, not to persistent storage in a cache file. To destroy data stored persistently, the Purge() member function must be called explicitly.

Definition at line 329 of file FileDataCache.h.

Member Function Documentation

◆ Add()

void pcl::FileDataCache::Add ( const FileDataCacheItem & item )

Adds the specified item to this cache.

The item will be stored in internal memory data structures, not in persistent cache files. To store cache items persistently, the Save() member function must be called for this object.

Note: This function is thread-safe.

◆ CacheName()

virtual String pcl::FileDataCache::CacheName ( ) const

inlinevirtual

Returns an identifying name for this cache object. The default implementation returns "File Cache". Derived classes should reimplement this function to return more specific names.

Definition at line 339 of file FileDataCache.h.

◆ Clear()

void pcl::FileDataCache::Clear ( )

Destroys and removes all cache items currently associated with this object.

Only items stored in internal memory data structures are removed by this function. Persistent storage is not altered.

Note: This function is thread-safe.

◆ DisableCompression()

void pcl::FileDataCache::DisableCompression ( bool disable = true )

inline

Disables compression of serialized cache item data.

See also: IsCompressionEnabled(), EnableCompression()

Definition at line 475 of file FileDataCache.h.

◆ EnableCompression()

void pcl::FileDataCache::EnableCompression ( bool enable = true )

inline

Enables compression of serialized cache item data.

See also: IsCompressionEnabled(), DisableCompression()

Definition at line 465 of file FileDataCache.h.

◆ FileSize()

fsize_type pcl::FileDataCache::FileSize ( ) const

Returns the current size in bytes of the cache file generated by this object. Returns zero if no cache file has been generated yet.

◆ Find()

const FileDataCacheItem* pcl::FileDataCache::Find	(	const String &	path,
		const IsoString &	key = `IsoString()`
	)		const

Returns the address of a file cache item corresponding to the specified file path and key, or nullptr if no such cache item could befound.

This function does not modify the cache or the time of last access of the item found.

Note: This function is thread-safe.

See also: Get()

◆ Get()

bool pcl::FileDataCache::Get	(	FileDataCacheItem &	item,
		const String &	path,
		const IsoString &	key = `IsoString()`
	)

Retrieves a copy of the existing cache data corresponding to the specified file path and key in the specified item.

Returns true iff a cache item for the specified path was found with the specified key in internal memory data structures, and its data were copied. If false is returned, the specified item will not be modified in any way.

Note: This function is thread-safe.

See also: Find()

◆ IsCompressionEnabled()

bool pcl::FileDataCache::IsCompressionEnabled ( ) const

inline

Returns true if data compression is enabled for serializations of cache item data performed with this object.

Data compression is enabled by default for newly constructed FileDataCache objects. Currently the Zstandard compression codec is applied for serialization of cache item data.

See also: EnableCompression(), DisableCompression()

Definition at line 455 of file FileDataCache.h.

◆ IsEmpty()

bool pcl::FileDataCache::IsEmpty ( ) const

Returns true iff this cache is empty, i.e. if there are no cache items associated with this object.

The returned value corresponds to the items currently stored in internal memory data structures. This does not necessarily equals the total number of items currently stored in persistent cache files.

Note: This function is thread-safe.

◆ IsModified()

bool pcl::FileDataCache::IsModified ( ) const

inline

Returns true iff this cache object has been modified.

See also: ModifiedCount()

Definition at line 581 of file FileDataCache.h.

◆ ItemsNeverExpire()

bool pcl::FileDataCache::ItemsNeverExpire ( ) const

inline

Returns true iff existing cache items associated with this object will never expire. This is achieved when the maximum item duration has been set to a value ≤ 0.

See also: MaxItemDuration(), SetMaxItemDuration()

Definition at line 408 of file FileDataCache.h.

◆ Load()

virtual void pcl::FileDataCache::Load ( )

virtual

Loads existing valid cache items from persistent storage.

All previously existing cache items stored in internal memory structures will be destroyed and deallocated before loading new data.

Note: Overriding implementations of this function must call the base class implementation.

◆ MaxItemDuration()

int pcl::FileDataCache::MaxItemDuration ( ) const

inline

Returns the maximum duration in days of a valid cache item.

Existing cache items that have not been accessed during a period longer than the value returned by this function will not be loaded from persistent data.

See also: SetMaxItemDuration(), ItemsNeverExpire()

Definition at line 379 of file FileDataCache.h.

◆ MinSupportedVersion()

virtual int pcl::FileDataCache::MinSupportedVersion ( ) const

inlinevirtual

Returns the minimum supported cache version. The default implementation returns 1.

Items with a version that is either less than the value returned by this function or greater than the current cache version will not be loaded from existing cache files. This allows for a basic version control system with a range of valid cache versions.

See also: Version()

Definition at line 365 of file FileDataCache.h.

◆ ModifiedCount()

int pcl::FileDataCache::ModifiedCount ( ) const

inline

Returns the number of cache modifications performed since the last cache file load operation.

Cache modifications happen each time a new cache item is added or an existing cache item is accessed. The modification count is reset to zero when the cache is cleared, when a cache file is loaded, and when the cache is saved to a disk file.

See also: IsModified()

Definition at line 571 of file FileDataCache.h.

◆ NewItem()

virtual FileDataCacheItem* pcl::FileDataCache::NewItem ( ) const

protectedpure virtual

Allocates and constructs a new cache item.

Returns a pointer to the newly created cache item. The new item will be owned by this object, which will destroy and deallocate it automatically when appropriate.

This is a pure virtual member function that must be reimplemented by all derived classes. This is because the data transported by a cache item is application-specific and cannot be known in advance by this base class.

◆ NumberOfItems()

size_type pcl::FileDataCache::NumberOfItems ( ) const

Returns the total number of cache items associated with this object.

The returned value corresponds to the number of cache items currently stored in internal data structures. This includes cache items loaded from existing cache files as well as items newly created and possibly still not copied to persistent storage.

Note: This function is thread-safe.

◆ Purge()

virtual void pcl::FileDataCache::Purge ( ) const

virtual

Destroys and deallocates all existing cache items, including all items currently in internal memory data structures as well as all items stored in persistent storage. This yields an empty cache file associated with this object.

Note: Overriding implementations of this function must call the base class implementation.

◆ Save()

virtual void pcl::FileDataCache::Save ( ) const

virtual

Writes all cache items associated with this object to persistent cache file storage.

Note: Overriding implementations of this function must call the base class implementation.

◆ SetMaxItemDuration()

virtual void pcl::FileDataCache::SetMaxItemDuration ( int days )

inlinevirtual

Sets the maximum duration in days for valid cache items. The supported range is from zero (meaning that cache items never expire) to 120 days.

Warning: If the specified number of days is ≤ 0, existing cache items will never expire. This is not recommended and can cause problems by increasing the size of cache files indiscriminately. In general, the default maximum duration of 30 days is quite appropriate for most applications.

See also: MaxItemDuration(), ItemsNeverExpire()

Definition at line 396 of file FileDataCache.h.

References pcl::Range().

◆ SetTokenSeparator()

void pcl::FileDataCache::SetTokenSeparator ( const IsoString & separator )

inline

Sets the token separator for this cache file.

The specified separator UTF-8 string will be used to separate items in cache item data serialized as ordered lists of string tokens. If an empty string is specified, the default token separator (a single newline character) will be used.

See also: TokenSeparator()

Definition at line 440 of file FileDataCache.h.

References pcl::GenericString< T, R, A >::IsEmpty().

◆ TokenSeparator()

IsoString pcl::FileDataCache::TokenSeparator ( ) const

inline

Returns the token separator used by this cache file.

Reimplementation-specific cache item data is serialized as ordered lists of string tokens in XML cache files. This member function returns an UTF-8 string (usually consisting of a single character) used to separate adjacent tokens in these data serializations.

The default token separator is a newline character.

See also: SetTokenSeparator()

Definition at line 425 of file FileDataCache.h.

◆ Version()

virtual int pcl::FileDataCache::Version ( ) const

inlinevirtual

Returns the current cache version. The default implementation returns 1.

See also: MinSupportedVersion()

Definition at line 349 of file FileDataCache.h.

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

FileDataCache.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FileDataCache()

◆ ~FileDataCache()

Member Function Documentation

◆ Add()

◆ CacheName()

◆ Clear()

◆ DisableCompression()

◆ EnableCompression()

◆ FileSize()

◆ Find()

◆ Get()

◆ IsCompressionEnabled()

◆ IsEmpty()

◆ IsModified()

◆ ItemsNeverExpire()

◆ Load()

◆ MaxItemDuration()

◆ MinSupportedVersion()

◆ ModifiedCount()

◆ NewItem()

◆ NumberOfItems()

◆ Purge()

◆ Save()

◆ SetMaxItemDuration()

◆ SetTokenSeparator()

◆ TokenSeparator()

◆ Version()