A default cache that provides a memory LRU cache and persistence of cached key-value pairs. More...

#include <DefaultCache.h>

Inheritance diagram for olp::cache::DefaultCache:

Collaboration diagram for olp::cache::DefaultCache:

Public Types
enum	StorageOpenResult { Success , OpenDiskPathFailure , ProtectedCacheCorrupted , NotReady }
	The storage open result type. More...

enum class	CacheType { kMutable , kProtected }
	The cache type. More...

Public Types inherited from olp::cache::KeyValueCache
using	ValueType = std::vector< unsigned char >
	The value type that is stored in the DB.

using	ValueTypePtr = std::shared_ptr< ValueType >
	The shared pointer type of the DB entry.

using	KeyListType = std::vector< std::string >
	An alias for the list of keys to be protected or released.

Public Member Functions
	DefaultCache (CacheSettings settings={})
	Creates the `DefaultCache` instance. More...

StorageOpenResult	Open ()
	Opens the cache to start read and write operations. More...

StorageOpenResult	Open (CacheType type)
	Creates a new cache of the corresponding type. More...

void	Close ()
	Closes the cache.

bool	Close (CacheType type)
	Closes the cache internally so that it is not keept open and thus blocking others from accessing it. More...

bool	Clear ()
	Clears the cache content. More...

void	Compact ()
	Compacts the underlying mutable cache storage. More...

bool	Put (const std::string &key, const boost::any &value, const Encoder &encoder, time_t expiry) override
	Stores the key-value pair in the cache. More...

bool	Put (const std::string &key, const KeyValueCache::ValueTypePtr value, time_t expiry) override
	Stores the raw binary data as a value in the cache. More...

boost::any	Get (const std::string &key, const Decoder &decoder) override
	Gets the key-value pair from the cache. More...

KeyValueCache::ValueTypePtr	Get (const std::string &key) override
	Gets the key and binary data from the cache. More...

bool	Remove (const std::string &key) override
	Removes the key-value pair from the cache. More...

bool	RemoveKeysWithPrefix (const std::string &prefix) override
	Removes the values with the keys that match the given prefix from the cache. More...

bool	Contains (const std::string &key) const override
	Check if key is in the cache. More...

bool	Protect (const KeyValueCache::KeyListType &keys) override
	Protects keys from eviction. More...

bool	Release (const KeyValueCache::KeyListType &keys) override
	Removes a list of keys from protection. More...

bool	IsProtected (const std::string &key) const override
	Checks if key is protected. More...

void	Promote (const std::string &key) override
	Promotes a key in the cache LRU when applicable. More...

OperationOutcome< ValueTypePtr >	Read (const std::string &key) override
	Gets the binary data from the cache. More...

OperationOutcomeEmpty	Write (const std::string &key, const ValueTypePtr &value, time_t expiry) override
	Stores the raw binary data as a value in the cache. More...

OperationOutcomeEmpty	Delete (const std::string &key) override
	Removes the key-value pair from the cache. More...

OperationOutcomeEmpty	DeleteByPrefix (const std::string &prefix) override
	Removes the values with the keys that match the given prefix from the cache. More...

uint64_t	Size (CacheType cache_type) const
	Gets size of the corresponding cache. More...

uint64_t	Size (uint64_t new_size)
	Sets maximum size for the mutable cache. Evict data that exceeds new maximum size. More...

Additional Inherited Members
Static Public Attributes inherited from olp::cache::KeyValueCache
static constexpr time_t	kDefaultExpiry = std::numeric_limits<time_t>::max()
	The expiry time of the key-value pair. More...

Detailed Description

A default cache that provides a memory LRU cache and persistence of cached key-value pairs.

Note: By default, the downloaded data is cached only in memory. To enable the persistent cache, define olp::cache::CacheSettings::disk_path. On iOS, the path is relative to the application data folder.

The default maximum size of the persistent cache is 32 MB. If the entire available disk space should be used, set olp::cache::CacheSettings::max_disk_storage to -1. The implementation of the default persistent cache is based on LevelDB. Due to the known LevelDB limitation, the default cache can be accessed only by one process exclusively.

By default, the maximum size of the memory cache is 1MB. To change it, set olp::cache::CacheSettings::max_memory_cache_size to the desired value.

Member Enumeration Documentation

◆ CacheType

enum olp::cache::DefaultCache::CacheType

strong

The cache type.

Enumerator
kMutable	The mutable cache type.
kProtected	The protected cache type.

◆ StorageOpenResult

enum olp::cache::DefaultCache::StorageOpenResult

The storage open result type.

Enumerator
Success	The operation succeeded.
OpenDiskPathFailure	The disk cache failure.
ProtectedCacheCorrupted	The protected disk cache is corrupted.
NotReady	The DefaultCache is closed.

Constructor & Destructor Documentation

◆ DefaultCache()

olp::cache::DefaultCache::DefaultCache ( CacheSettings settings = {} )

explicit

Creates the DefaultCache instance.

Parameters

settings The cache settings.

Member Function Documentation

◆ Clear()

bool olp::cache::DefaultCache::Clear ( )

Clears the cache content.

Returns: True if the operation is successful; false otherwise.

◆ Close()

bool olp::cache::DefaultCache::Close ( CacheType type )

Closes the cache internally so that it is not keept open and thus blocking others from accessing it.

Parameters

type	The type of cache to close.

Returns: true if the cache was closed successfully; false otherwise.

◆ Compact()

void olp::cache::DefaultCache::Compact ( )

Compacts the underlying mutable cache storage.

In particular, deleted and overwritten versions are discarded, and the data is rearranged to reduce the cost of operations needed to access the data. In some cases this operation might take a very long time, so use with care. You generally don't have to call this, but it can be useful to optimize preloaded databases or compact before you shut down the system to ensure quick startup time.

Note: This operation is blocking and under mutex lock blocking any other operation in parallel for the time of the compacting operation. Be aware that automatic asynchronous compacting operation is triggered internally once the database size exceeds the CacheSettings::max_disk_storage size.; After the compaction is finished the cache is checked on level-0 file presence. If there are still some files present another round of compaction is performed.

◆ Contains()

bool olp::cache::DefaultCache::Contains ( const std::string & key ) const

overridevirtual

Check if key is in the cache.

Parameters

key	The key for the value.

Returns: True if the key/value cached ; false otherwise.

Reimplemented from olp::cache::KeyValueCache.

◆ Delete()

OperationOutcomeEmpty olp::cache::DefaultCache::Delete ( const std::string & key )

overridevirtual

Removes the key-value pair from the cache.

Parameters

key	The key for the value.

Returns: An error if the data could not be removed from the cache.

Reimplemented from olp::cache::KeyValueCache.

◆ DeleteByPrefix()

OperationOutcomeEmpty olp::cache::DefaultCache::DeleteByPrefix ( const std::string & prefix )

overridevirtual

Removes the values with the keys that match the given prefix from the cache.

Parameters

prefix The prefix that matches the keys.

Returns: An error if the data could not be removed from the cache.

Reimplemented from olp::cache::KeyValueCache.

◆ Get() [1/2]

KeyValueCache::ValueTypePtr olp::cache::DefaultCache::Get ( const std::string & key )

overridevirtual

Gets the key and binary data from the cache.

Parameters

key	The key that is used to look for the binary data.

Returns: The key and binary data.

Implements olp::cache::KeyValueCache.

◆ Get() [2/2]

boost::any olp::cache::DefaultCache::Get	(	const std::string &	key,
		const Decoder &	decoder
	)

overridevirtual

Gets the key-value pair from the cache.

Parameters

key	The key that is used to look for the key-value pair.
decoder	Decodes the value from a string.

Returns: The key-value pair.

Implements olp::cache::KeyValueCache.

◆ IsProtected()

bool olp::cache::DefaultCache::IsProtected ( const std::string & key ) const

overridevirtual

Checks if key is protected.

Parameters

key	The key or prefix.

Returns: True if the key are in the protected list; false otherwise.

Reimplemented from olp::cache::KeyValueCache.

◆ Open() [1/2]

StorageOpenResult olp::cache::DefaultCache::Open ( )

Opens the cache to start read and write operations.

Returns: StorageOpenResult if there are problems opening any of the provided paths on the disk.

Note: If the cache cannot be opened or repaired, it is deleted.

◆ Open() [2/2]

StorageOpenResult olp::cache::DefaultCache::Open ( CacheType type )

Creates a new cache of the corresponding type.

Parameters

type	The type of cache to open.

Returns: Success if the cache is created or already open, NotReady if DefaultCache is closed, and OpenDiskPathFailure if there are problems opening the provided path on the disk.

Note: If the cache cannot be opened or repaired, it is deleted.

◆ Promote()

void olp::cache::DefaultCache::Promote ( const std::string & key )

overridevirtual

Promotes a key in the cache LRU when applicable.

Parameters

key	The key to promote in the cache LRU.

Reimplemented from olp::cache::KeyValueCache.

◆ Protect()

bool olp::cache::DefaultCache::Protect ( const KeyValueCache::KeyListType & keys )

overridevirtual

Protects keys from eviction.

You can use keys or prefixes to protect single keys or entire catalogs, layers, or version.

Parameters

keys	The list of keys or prefixes.

Returns: True if the keys are added to the protected list; false otherwise.

Reimplemented from olp::cache::KeyValueCache.

◆ Put() [1/2]

bool olp::cache::DefaultCache::Put	(	const std::string &	key,
		const boost::any &	value,
		const Encoder &	encoder,
		time_t	expiry
	)

overridevirtual

Stores the key-value pair in the cache.

Parameters

key	The key for this value.
value	The value of any type.
encoder	Encodes the specified value into a string.
expiry	The expiry time (in seconds) of the key-value pair.

Returns: True if the operation is successful; false otherwise.

Implements olp::cache::KeyValueCache.

◆ Put() [2/2]

bool olp::cache::DefaultCache::Put	(	const std::string &	key,
		const KeyValueCache::ValueTypePtr	value,
		time_t	expiry
	)

overridevirtual

Stores the raw binary data as a value in the cache.

Parameters

key	The key for this value.
value	The binary data that should be stored.
expiry	The expiry time (in seconds) of the key-value pair.

Returns: True if the operation is successful; false otherwise.

Implements olp::cache::KeyValueCache.

◆ Read()

OperationOutcome<ValueTypePtr> olp::cache::DefaultCache::Read ( const std::string & key )

overridevirtual

Gets the binary data from the cache.

Parameters

key	The key that is used to look for the binary data.

Returns: The binary data or an error if the data could not be retrieved from the cache.

Reimplemented from olp::cache::KeyValueCache.

◆ Release()

bool olp::cache::DefaultCache::Release ( const KeyValueCache::KeyListType & keys )

overridevirtual

Removes a list of keys from protection.

The provided keys can be full keys or prefixes only.

Parameters

keys	The list of keys or prefixes.

Returns: True if the keys are removed from the protected list; false otherwise.

Reimplemented from olp::cache::KeyValueCache.

◆ Remove()

bool olp::cache::DefaultCache::Remove ( const std::string & key )

overridevirtual

Removes the key-value pair from the cache.

Parameters

key	The key for the value.

Returns: True if the operation is successful; false otherwise.

Implements olp::cache::KeyValueCache.

◆ RemoveKeysWithPrefix()

bool olp::cache::DefaultCache::RemoveKeysWithPrefix ( const std::string & prefix )

overridevirtual

Removes the values with the keys that match the given prefix from the cache.

Parameters

prefix The prefix that matches the keys.

Returns: True if the values are removed; false otherwise.

Implements olp::cache::KeyValueCache.

◆ Size() [1/2]

uint64_t olp::cache::DefaultCache::Size ( CacheType cache_type ) const

Gets size of the corresponding cache.

Parameters

cache_type The type of a cache.

Returns: Size of the corresponding cache.

◆ Size() [2/2]

uint64_t olp::cache::DefaultCache::Size ( uint64_t new_size )

Sets maximum size for the mutable cache. Evict data that exceeds new maximum size.

Parameters

new_size The new maximum size.

Returns: The size of the evicted data. If no data evicted return 0u.

Note: Currently this operation may take a lot of time and RAM to finish.

◆ Write()

OperationOutcomeEmpty olp::cache::DefaultCache::Write	(	const std::string &	key,
		const ValueTypePtr &	value,
		time_t	expiry
	)

overridevirtual

Stores the raw binary data as a value in the cache.

Parameters

key	The key for this value.
value	The binary data that should be stored.
expiry	The expiry time (in seconds) of the key-value pair.

Returns: An error if the data could not be written to the cache.

Reimplemented from olp::cache::KeyValueCache.

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

olp-cpp-sdk-core/include/olp/core/cache/DefaultCache.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ CacheType

◆ StorageOpenResult

Constructor & Destructor Documentation

◆ DefaultCache()

Member Function Documentation

◆ Clear()

◆ Close()

◆ Compact()

◆ Contains()

◆ Delete()

◆ DeleteByPrefix()

◆ Get() [1/2]

◆ Get() [2/2]

◆ IsProtected()

◆ Open() [1/2]

◆ Open() [2/2]

◆ Promote()

◆ Protect()

◆ Put() [1/2]

◆ Put() [2/2]

◆ Read()

◆ Release()

◆ Remove()

◆ RemoveKeysWithPrefix()

◆ Size() [1/2]

◆ Size() [2/2]

◆ Write()