Template Class Cache

Nested Relationships

Class Documentation

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

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.

Note

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.

Note

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

Public Functions

Cache(std::size_t maxElements = 0)

Ctor

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

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

Cache(Cache const&)
Cache(Cache&&)
Cache &operator=(Cache const&)
Cache &operator=(Cache&&)
~Cache()

Dtor.

template<typename Generator>
Value 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.

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

Value operator[](Key const &key)
void 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.

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

std::size_t size() const

Return the number of values in the cache

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

std::vector<Key> keys() const

Return all keys in the cache, most recent first

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

bool contains(Key const &key)

Does the cache contain the key?

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

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

std::size_t capacity() const

Return the capacity of the cache

No exceptions can be thrown.

void reserve(std::size_t maxElements)

Change the capacity of the cache

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

void flush()

Empty the cache

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