#include <bdlcc_cache.h>

Detailed Description

template<class KEY, class VALUE, class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>
class bdlcc::Cache< KEY, VALUE, HASH, EQUAL >

This class represents a simple in-process key-value store supporting a variety of eviction policies.

See bdlcc_cache

Public Types
typedef bsl::shared_ptr< VALUE >	ValuePtrType

typedef bsl::function< void(const ValuePtrType &)>	PostEvictionCallback

typedef bsl::pair< KEY, ValuePtrType >	KVType

Public Member Functions
	Cache (bslma::Allocator *basicAllocator=0)

	Cache (CacheEvictionPolicy::Enum evictionPolicy, bsl::size_t lowWatermark, bsl::size_t highWatermark, bslma::Allocator *basicAllocator=0)

	Cache (CacheEvictionPolicy::Enum evictionPolicy, bsl::size_t lowWatermark, bsl::size_t highWatermark, const HASH &hashFunction, const EQUAL &equalFunction, bslma::Allocator *basicAllocator=0)

	~Cache ()=default

void	clear ()

int	erase (const KEY &key)

template<class INPUT_ITERATOR >
int	eraseBulk (INPUT_ITERATOR begin, INPUT_ITERATOR end)

int	eraseBulk (const bsl::vector< KEY > &keys)

void	insert (const KEY &key, const VALUE &value)

void	insert (const KEY &key, bslmf::MovableRef< VALUE > value)

void	insert (bslmf::MovableRef< KEY > key, const VALUE &value)

void	insert (bslmf::MovableRef< KEY > key, bslmf::MovableRef< VALUE > value)

void	insert (const KEY &key, const ValuePtrType &valuePtr)

void	insert (bslmf::MovableRef< KEY > key, const ValuePtrType &valuePtr)

template<class INPUT_ITERATOR >
int	insertBulk (INPUT_ITERATOR begin, INPUT_ITERATOR end)

int	insertBulk (const bsl::vector< KVType > &data)

int	insertBulk (bslmf::MovableRef< bsl::vector< KVType > > data)

int	popFront ()

void	setPostEvictionCallback (const PostEvictionCallback &postEvictionCallback)

int	tryGetValue (bsl::shared_ptr< VALUE > *value, const KEY &key, bool modifyEvictionQueue=true)

EQUAL	equalFunction () const

CacheEvictionPolicy::Enum	evictionPolicy () const

HASH	hashFunction () const

bsl::size_t	highWatermark () const

bsl::size_t	lowWatermark () const

bsl::size_t	size () const

template<class VISITOR >
void	visit (VISITOR &visitor) const

Friends
class	Cache_TestUtil< KEY, VALUE, HASH, EQUAL >

Member Typedef Documentation

◆ KVType

template<class KEY , class VALUE , class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>

typedef bsl::pair<KEY, ValuePtrType> bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::KVType

Value type of a bulk insert entry.

◆ PostEvictionCallback

template<class KEY , class VALUE , class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>

typedef bsl::function<void(const ValuePtrType&)> bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::PostEvictionCallback

Type of function to call after an item has been evicted from the cache.

◆ ValuePtrType

template<class KEY , class VALUE , class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>

typedef bsl::shared_ptr<VALUE> bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::ValuePtrType

Shared pointer type pointing to value type.

Constructor & Destructor Documentation

◆ Cache() [1/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::Cache ( bslma::Allocator * basicAllocator = 0 )

explicit

Create an empty LRU cache having no size limit. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

◆ Cache() [2/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::Cache	(	CacheEvictionPolicy::Enum	evictionPolicy,
		bsl::size_t	lowWatermark,
		bsl::size_t	highWatermark,
		bslma::Allocator *	basicAllocator = `0`
	)

Create an empty cache using the specified evictionPolicy and the specified lowWatermark and highWatermark. Optionally specify the basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Precondition: The behavior is undefined unless lowWatermark <= highWatermark, 1 <= lowWatermark, and 1 <= highWatermark.

◆ Cache() [3/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::Cache	(	CacheEvictionPolicy::Enum	evictionPolicy,
		bsl::size_t	lowWatermark,
		bsl::size_t	highWatermark,
		const HASH &	hashFunction,
		const EQUAL &	equalFunction,
		bslma::Allocator *	basicAllocator = `0`
	)

Create an empty cache using the specified evictionPolicy, lowWatermark, and highWatermark. The specified hashFunction is used to generate the hash values for a given key, and the specified equalFunction is used to determine whether two keys have the same value. Optionally specify the basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

Precondition: The behavior is undefined unless lowWatermark <= highWatermark, 1 <= lowWatermark, and 1 <= highWatermark.

◆ ~Cache()

template<class KEY , class VALUE , class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>

bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::~Cache ( )

default

Destroy this object.

Member Function Documentation

◆ clear()

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::clear ( )

Remove all items from this cache. Do not invoke the post-eviction callback.

◆ equalFunction()

template<class KEY , class VALUE , class HASH , class EQUAL >

EQUAL bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::equalFunction ( ) const

inline

Return (a copy of) the key-equality functor used by this cache that returns true if two KEY objects have the same value, and false otherwise.

◆ erase()

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::erase ( const KEY & key )

Remove the item having the specified key from this cache. Invoke the post-eviction callback for the removed item. Return 0 on success and 1 if key does not exist.

◆ eraseBulk() [1/2]

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::eraseBulk ( const bsl::vector< KEY > & keys )

inline

Remove the items having the specified keys from this cache. Invoke the post-eviction callback for each removed item. Return the number of items successfully removed.

◆ eraseBulk() [2/2]

template<class KEY , class VALUE , class HASH , class EQUAL >

template<class INPUT_ITERATOR >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::eraseBulk	(	INPUT_ITERATOR	begin,
		INPUT_ITERATOR	end
	)

Remove the items having the keys in the specified range [ begin, end ), from this cache. Invoke the post-eviction callback for each removed item. Return the number of items successfully removed.

◆ evictionPolicy()

template<class KEY , class VALUE , class HASH , class EQUAL >

CacheEvictionPolicy::Enum bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::evictionPolicy ( ) const

inline

Return the eviction policy used by this cache.

◆ hashFunction()

template<class KEY , class VALUE , class HASH , class EQUAL >

HASH bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::hashFunction ( ) const

inline

Return (a copy of) the unary hash functor used by this cache to generate a hash value (of type std::size_t) for a KEY object.

◆ highWatermark()

template<class KEY , class VALUE , class HASH , class EQUAL >

bsl::size_t bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::highWatermark ( ) const

inline

Return the high watermark of this cache, which is the size at which eviction of existing items begins.

◆ insert() [1/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	bslmf::MovableRef< KEY >	key,
		bslmf::MovableRef< VALUE >	value
	)

◆ insert() [2/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	bslmf::MovableRef< KEY >	key,
		const VALUE &	value
	)

◆ insert() [3/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	bslmf::MovableRef< KEY >	key,
		const ValuePtrType &	valuePtr
	)

◆ insert() [4/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	const KEY &	key,
		bslmf::MovableRef< VALUE >	value
	)

◆ insert() [5/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	const KEY &	key,
		const VALUE &	value
	)

inline

Move the specified key and its associated value into this cache. If key already exists, then its value will be replaced with value.

Note: Note that all the methods that take moved objects provide the basic but not the strong exception guarantee – throws may occur after the objects are moved out of; the cache will not be modified, but key or value may be changed. Also note that key must be copyable, even if it is moved.

◆ insert() [6/6]

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insert	(	const KEY &	key,
		const ValuePtrType &	valuePtr
	)

inline

Insert the specified key and its associated valuePtr into this cache. If key already exists, then its value will be replaced with value.

Note: Note that the method with key moved provides the basic but not the strong exception guarantee – if a throw occurs, the cache will not be modified, but key may be changed. Also note that key must be copyable, even if it is moved.

◆ insertBulk() [1/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insertBulk ( bslmf::MovableRef< bsl::vector< KVType > > data )

Insert the specified data (composed of Key-Value pairs) into this cache. If a key already exists, then its value will be replaced with the value. Return the number of items successfully inserted. If an exception occurs during this action, we provide only the basic guarantee - both this cache and data will be in some valid but unspecified state.

◆ insertBulk() [2/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insertBulk ( const bsl::vector< KVType > & data )

inline

Insert the specified data (composed of Key-Value pairs) into this cache. If a key already exists, then its value will be replaced with the value. Return the number of items successfully inserted.

◆ insertBulk() [3/3]

template<class KEY , class VALUE , class HASH , class EQUAL >

template<class INPUT_ITERATOR >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::insertBulk	(	INPUT_ITERATOR	begin,
		INPUT_ITERATOR	end
	)

Insert the specified range of Key-Value pairs specified by [ begin, end ) into this cache. If a key already exists, then its value will be replaced with the value. Return the number of items successfully inserted.

◆ lowWatermark()

template<class KEY , class VALUE , class HASH , class EQUAL >

bsl::size_t bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::lowWatermark ( ) const

inline

Return the low watermark of this cache, which is the size at which eviction of existing items ends.

◆ popFront()

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::popFront ( )

inline

Remove the item at the front of the eviction queue. Invoke the post-eviction callback for the removed item. Return 0 on success, and 1 if this cache is empty.

◆ setPostEvictionCallback()

template<class KEY , class VALUE , class HASH , class EQUAL >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::setPostEvictionCallback ( const PostEvictionCallback & postEvictionCallback )

Set the post-eviction callback to the specified postEvictionCallback. The post-eviction callback is invoked for each item evicted or removed from this cache.

◆ size()

template<class KEY , class VALUE , class HASH , class EQUAL >

bsl::size_t bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::size ( ) const

inline

Return the current size of this cache.

◆ tryGetValue()

template<class KEY , class VALUE , class HASH , class EQUAL >

int bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::tryGetValue	(	bsl::shared_ptr< VALUE > *	value,
		const KEY &	key,
		bool	modifyEvictionQueue = `true`
	)

Load, into the specified value, the value associated with the specified key in this cache. If the optionally specified modifyEvictionQueue is true and the eviction policy is LRU, then move the cached item to the back of the eviction queue. Return 0 on success, and 1 if key does not exist in this cache.

Note: Note that a write lock is acquired only if this queue is modified.

◆ visit()

template<class KEY , class VALUE , class HASH , class EQUAL >

template<class VISITOR >

void bdlcc::Cache< KEY, VALUE, HASH, EQUAL >::visit ( VISITOR & visitor ) const

Call the specified visitor for every item stored in this cache in the order of the eviction queue until visitor returns false. The VISITOR type must be a callable object that can be invoked in the same way as the function bool (const KEY&, const VALUE&)

Friends And Related Symbol Documentation

◆ Cache_TestUtil< KEY, VALUE, HASH, EQUAL >

template<class KEY , class VALUE , class HASH = bsl::hash<KEY>, class EQUAL = bsl::equal_to<KEY>>

friend class Cache_TestUtil< KEY, VALUE, HASH, EQUAL >

friend

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

bdlcc_cache.h

Detailed Description

Public Types

Public Member Functions

Friends

Member Typedef Documentation

◆ KVType

◆ PostEvictionCallback

◆ ValuePtrType

Constructor & Destructor Documentation

◆ Cache() [1/3]

◆ Cache() [2/3]

◆ Cache() [3/3]

◆ ~Cache()

Member Function Documentation

◆ clear()

◆ equalFunction()

◆ erase()

◆ eraseBulk() [1/2]

◆ eraseBulk() [2/2]

◆ evictionPolicy()

◆ hashFunction()

◆ highWatermark()

◆ insert() [1/6]

◆ insert() [2/6]

◆ insert() [3/6]

◆ insert() [4/6]

◆ insert() [5/6]

◆ insert() [6/6]

◆ insertBulk() [1/3]

◆ insertBulk() [2/3]

◆ insertBulk() [3/3]

◆ lowWatermark()

◆ popFront()

◆ setPostEvictionCallback()

◆ size()

◆ tryGetValue()

◆ visit()

Friends And Related Symbol Documentation

◆ Cache_TestUtil< KEY, VALUE, HASH, EQUAL >