lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred > Class Template Reference

Cache of most recently used values. More...

#include <Cache.h>

Public Member Functions
	Cache (std::size_t maxElements=0)
	Ctor.
	Cache (Cache const &)=default
	Cache (Cache &&)=default
Cache &	operator= (Cache const &)=default
Cache &	operator= (Cache &&)=default
	~Cache ()=default
	Dtor.
template<typename Generator >
Value	operator() (Key const &key, Generator func)
	Lookup or generate a value.
Value	operator[] (Key const &key)
void	add (Key const &key, Value const &value)
	Add a value to the cache.
std::size_t	size () const
	Return the number of values in the cache.
std::vector< Key >	keys () const
	Return all keys in the cache, most recent first.
bool	contains (Key const &key)
	Does the cache contain the key?
std::optional< Value >	get (Key const &key)
	Return the cached value if it exists.
std::size_t	capacity () const
	Return the capacity of the cache.
void	reserve (std::size_t maxElements)
	Change the capacity of the cache.
void	flush ()
	Empty the cache.
	Cache (std::size_t maxElements=0)
	Ctor.
	Cache (Cache const &)=default
	Cache (Cache &&)=default
Cache &	operator= (Cache const &)=default
Cache &	operator= (Cache &&)=default
	~Cache ()=default
	Dtor.
template<typename Generator >
Value	operator() (Key const &key, Generator func)
	Lookup or generate a value.
Value	operator[] (Key const &key)
void	add (Key const &key, Value const &value)
	Add a value to the cache.
std::size_t	size () const
	Return the number of values in the cache.
std::vector< Key >	keys () const
	Return all keys in the cache, most recent first.
bool	contains (Key const &key)
	Does the cache contain the key?
std::optional< Value >	get (Key const &key)
	Return the cached value if it exists.
std::size_t	capacity () const
	Return the capacity of the cache.
void	reserve (std::size_t maxElements)
	Change the capacity of the cache.
void	flush ()
	Empty the cache.

Detailed Description

template<typename Key, typename Value, typename KeyHash, typename KeyPred>
class lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >

Cache of most recently used values.

This object stores the most recent maxElements values, where maxElements is set in the constructor. Objects (of type Value) are stored by a key (of type Key; hence the need to provide a KeyHash and KeyPred), and the class presents a dict-like interface. Objects may be added to (add) and retrieved from (operator[]) the cache. For ease of use, an interface (operator()) is also provided that will check the cache for an existing key, and if the key is not present, generate it with a function provided by the user.

Note

Value and Key must be copyable.

This header (Cache.h) should generally only be included in source files, not other header files, because you probably don't want all of the boost::multi_index includes in your header. We suggest you se the CacheFwd.h file in your header instead, and hold the Cache as a std::unique_ptr.

Python bindings (for pybind11) are available in lsst/cpputils/python/Cache.h.

Definition at line 75 of file Cache.h.

Constructor & Destructor Documentation

Cache() [1/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( std::size_t maxElements = 0 )

inline

Ctor.

The maximum number of elements may be zero (default), in which case the cache is permitted to grow without limit.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

Definition at line 85 of file Cache.h.

                                   : _maxElements(maxElements) {
        _container.template get<Hash>().reserve(maxElements);
#ifdef LSST_CACHE_DEBUG
        _debuggingEnabled = false;
        _hits = 0;
        _total = 0;
        _requests.reserve(maxElements);
#endif
    }

Cache() [2/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( Cache< Key, Value, KeyHash, KeyPred > const & )

default

Cache() [3/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( Cache< Key, Value, KeyHash, KeyPred > && )

default

~Cache() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::~Cache ( )

default

Dtor.

Cache() [4/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( std::size_t maxElements = 0 )

inline

Ctor.

The maximum number of elements may be zero (default), in which case the cache is permitted to grow without limit.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

Definition at line 85 of file Cache.h.

                                   : _maxElements(maxElements) {
        _container.template get<Hash>().reserve(maxElements);
#ifdef LSST_CACHE_DEBUG
        _debuggingEnabled = false;
        _hits = 0;
        _total = 0;
        _requests.reserve(maxElements);
#endif
    }

Cache() [5/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( Cache< Key, Value, KeyHash, KeyPred > const & )

default

Cache() [6/6]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::Cache ( Cache< Key, Value, KeyHash, KeyPred > && )

default

~Cache() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::~Cache ( )

default

Dtor.

Member Function Documentation

add() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::add	(	Key const &	key,
		Value const &	value )

Add a value to the cache.

If the key is already in the cache, the existing value will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 318 of file Cache.h.

                                                                                {
    auto result = _lookup(key);
    if (!result.second) {
        _addNew(key, value);
    }
}

add() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::add	(	Key const &	key,
		Value const &	value )

Add a value to the cache.

If the key is already in the cache, the existing value will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

capacity() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::size_t lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::capacity ( ) const

inline

Return the capacity of the cache.

Exception Safety

No exceptions can be thrown.

Definition at line 201 of file Cache.h.

{ return _maxElements; }

capacity() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::size_t lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::capacity ( ) const

inline

Return the capacity of the cache.

Exception Safety

No exceptions can be thrown.

Definition at line 201 of file Cache.h.

{ return _maxElements; }

contains() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

bool lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::contains ( Key const & key )

inline

Does the cache contain the key?

If the key is in the cache, it will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 178 of file Cache.h.

{ return _lookup(key).second; }

contains() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

bool lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::contains ( Key const & key )

inline

Does the cache contain the key?

If the key is in the cache, it will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 178 of file Cache.h.

{ return _lookup(key).second; }

flush() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::flush

(

)

Empty the cache.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 336 of file Cache.h.

                                                {
    while (size() > 0) {
        _container.template get<Sequence>().pop_back();
    }
}

flush() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::flush

(

)

Empty the cache.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

get() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::optional< Value > lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::get ( Key const & key )

inline

Return the cached value if it exists.

If the key is in the cache, it will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 188 of file Cache.h.

                                           {
        auto result = _lookup(key);
        if (result.second) {
            return std::optional<Value>(result.first->second);
        } else {
            return std::optional<Value>();
        }
    }

get() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::optional< Value > lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::get ( Key const & key )

inline

Return the cached value if it exists.

If the key is in the cache, it will be promoted to the most recently used value.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 188 of file Cache.h.

                                           {
        auto result = _lookup(key);
        if (result.second) {
            return std::optional<Value>(result.first->second);
        } else {
            return std::optional<Value>();
        }
    }

keys() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::vector< Key > lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::keys

(

)

const

Return all keys in the cache, most recent first.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

Definition at line 326 of file Cache.h.

                                                               {
    std::vector<Key> result;
    result.reserve(size());
    for (auto & keyValue : _container.template get<Sequence>()) {
        result.push_back(keyValue.first);
    }
    return result;
}

keys() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::vector< Key > lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::keys

(

)

const

Return all keys in the cache, most recent first.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

operator()() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

template<typename Generator >

Value lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator()	(	Key const &	key,
		Generator	func )

Lookup or generate a value.

If the key is in the cache, the corresponding value is returned. Otherwise, a value is generated by the provided function which is cached and returned. Thus, the (expensive) Generator function only fires if the corresponding value is not already cached.

The Generator function signature should be:

Value func(Key const& key);

Given the possibility of lambdas, we could have made the required function signature so that it took no arguments. However, it's possible the user has some function that produces a value when given a key, so chose to adopt that signature; any other signature would likely require use of a lambda always.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 294 of file Cache.h.

  {
    auto result = _lookup(key);
    if (result.second) {
        return result.first->second;
    }
    Value value = func(key);
    _addNew(key, value);
    return value;
}

operator()() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

template<typename Generator >

Value lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator()	(	Key const &	key,
		Generator	func )

Lookup or generate a value.

If the key is in the cache, the corresponding value is returned. Otherwise, a value is generated by the provided function which is cached and returned. Thus, the (expensive) Generator function only fires if the corresponding value is not already cached.

The Generator function signature should be:

Value func(Key const& key);

Given the possibility of lambdas, we could have made the required function signature so that it took no arguments. However, it's possible the user has some function that produces a value when given a key, so chose to adopt that signature; any other signature would likely require use of a lambda always.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

operator=() [1/4]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Cache & lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator= ( Cache< Key, Value, KeyHash, KeyPred > && )

default

operator=() [2/4]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Cache & lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator= ( Cache< Key, Value, KeyHash, KeyPred > && )

default

operator=() [3/4]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Cache & lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator= ( Cache< Key, Value, KeyHash, KeyPred > const & )

default

operator=() [4/4]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Cache & lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator= ( Cache< Key, Value, KeyHash, KeyPred > const & )

default

operator[]() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Value lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator[]

(

Key const &

key

)

Definition at line 308 of file Cache.h.

                                                                    {
    auto result = _lookup(key);
    if (result.second) {
        return result.first->second;
    }
    throw LSST_EXCEPT(pex::exceptions::NotFoundError,
                      (boost::format("Unable to find key: %s") % key).str());
}

operator[]() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

Value lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::operator[]

(

Key const &

key

)

reserve() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::reserve ( std::size_t maxElements )

inline

Change the capacity of the cache.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 208 of file Cache.h.

{ _maxElements = maxElements; _trim(); }

reserve() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

void lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::reserve ( std::size_t maxElements )

inline

Change the capacity of the cache.

Exception Safety

Basic exception safety: exceptions will leave the system in a valid but unpredictable state.

Definition at line 208 of file Cache.h.

{ _maxElements = maxElements; _trim(); }

size() [1/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::size_t lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::size ( ) const

inline

Return the number of values in the cache.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

Definition at line 161 of file Cache.h.

{ return _container.size(); }

size() [2/2]

template<typename Key , typename Value , typename KeyHash , typename KeyPred >

std::size_t lsst::cpputils::Cache< Key, Value, KeyHash, KeyPred >::size ( ) const

inline

Return the number of values in the cache.

Exception Safety

Strong exception safety: exceptions will return the system to previous state.

Definition at line 161 of file Cache.h.

{ return _container.size(); }

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-8.0.0/Linux64/cpputils/g9ddcbc5298+d4bad12328/include/lsst/cpputils/Cache.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-8.0.0/Linux64/cpputils/g9ddcbc5298+d4bad12328/include/lsst/utils/Cache.h