LSST Applications g0b6bd0c080+a72a5dd7e6,g1182afd7b4+2a019aa3bb,g17e5ecfddb+2b8207f7de,g1d67935e3f+06cf436103,g38293774b4+ac198e9f13,g396055baef+6a2097e274,g3b44f30a73+6611e0205b,g480783c3b1+98f8679e14,g48ccf36440+89c08d0516,g4b93dc025c+98f8679e14,g5c4744a4d9+a302e8c7f0,g613e996a0d+e1c447f2e0,g6c8d09e9e7+25247a063c,g7271f0639c+98f8679e14,g7a9cd813b8+124095ede6,g9d27549199+a302e8c7f0,ga1cf026fa3+ac198e9f13,ga32aa97882+7403ac30ac,ga786bb30fb+7a139211af,gaa63f70f4e+9994eb9896,gabf319e997+ade567573c,gba47b54d5d+94dc90c3ea,gbec6a3398f+06cf436103,gc6308e37c7+07dd123edb,gc655b1545f+ade567573c,gcc9029db3c+ab229f5caf,gd01420fc67+06cf436103,gd877ba84e5+06cf436103,gdb4cecd868+6f279b5b48,ge2d134c3d5+cc4dbb2e3f,ge448b5faa6+86d1ceac1d,gecc7e12556+98f8679e14,gf3ee170dca+25247a063c,gf4ac96e456+ade567573c,gf9f5ea5b4d+ac198e9f13,gff490e6085+8c2580be5c,w.2022.27
LSST Data Management Base Package
Classes | Public Member Functions | List of all members
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. More...
 
 Cache (Cache const &)=default
 
 Cache (Cache &&)=default
 
Cacheoperator= (Cache const &)=default
 
Cacheoperator= (Cache &&)=default
 
 ~Cache ()=default
 Dtor. More...
 
template<typename Generator >
Value operator() (Key const &key, Generator func)
 Lookup or generate a value. More...
 
Value operator[] (Key const &key)
 
void add (Key const &key, Value const &value)
 Add a value to the cache. More...
 
std::size_t size () const
 Return the number of values in the cache. More...
 
std::vector< Key > keys () const
 Return all keys in the cache, most recent first. More...
 
bool contains (Key const &key)
 Does the cache contain the key? More...
 
std::optional< Value > get (Key const &key)
 Return the cached value if it exists. More...
 
std::size_t capacity () const
 Return the capacity of the cache. More...
 
void reserve (std::size_t maxElements)
 Change the capacity of the cache. More...
 
void flush ()
 Empty the cache. More...
 
 Cache (std::size_t maxElements=0)
 Ctor. More...
 
 Cache (Cache const &)=default
 
 Cache (Cache &&)=default
 
Cacheoperator= (Cache const &)=default
 
Cacheoperator= (Cache &&)=default
 
 ~Cache ()=default
 Dtor. More...
 
template<typename Generator >
Value operator() (Key const &key, Generator func)
 Lookup or generate a value. More...
 
Value operator[] (Key const &key)
 
void add (Key const &key, Value const &value)
 Add a value to the cache. More...
 
std::size_t size () const
 Return the number of values in the cache. More...
 
std::vector< Key > keys () const
 Return all keys in the cache, most recent first. More...
 
bool contains (Key const &key)
 Does the cache contain the key? More...
 
std::optional< Value > get (Key const &key)
 Return the cached value if it exists. More...
 
std::size_t capacity () const
 Return the capacity of the cache. More...
 
void reserve (std::size_t maxElements)
 Change the capacity of the cache. More...
 
void flush ()
 Empty the cache. More...
 

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.

85 : _maxElements(maxElements) {
86 _container.template get<Hash>().reserve(maxElements);
87#ifdef LSST_CACHE_DEBUG
88 _debuggingEnabled = false;
89 _hits = 0;
90 _total = 0;
91 _requests.reserve(maxElements);
92#endif
93 }

◆ 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.

85 : _maxElements(maxElements) {
86 _container.template get<Hash>().reserve(maxElements);
87#ifdef LSST_CACHE_DEBUG
88 _debuggingEnabled = false;
89 _hits = 0;
90 _total = 0;
91 _requests.reserve(maxElements);
92#endif
93 }

◆ 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.

318 {
319 auto result = _lookup(key);
320 if (!result.second) {
321 _addNew(key, value);
322 }
323}
py::object result
Definition: _schema.cc:429

◆ 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.

201{ 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.

201{ 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.

178{ 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.

178{ 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.

336 {
337 while (size() > 0) {
338 _container.template get<Sequence>().pop_back();
339 }
340}
std::size_t size() const
Return the number of values in the cache.
Definition: Cache.h:161

◆ 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.

188 {
189 auto result = _lookup(key);
190 if (result.second) {
191 return std::optional<Value>(result.first->second);
192 } else {
193 return std::optional<Value>();
194 }
195 }

◆ 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.

188 {
189 auto result = _lookup(key);
190 if (result.second) {
191 return std::optional<Value>(result.first->second);
192 } else {
193 return std::optional<Value>();
194 }
195 }

◆ keys() [1/2]

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

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.

326 {
328 result.reserve(size());
329 for (auto & keyValue : _container.template get<Sequence>()) {
330 result.push_back(keyValue.first);
331 }
332 return result;
333}

◆ 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.

297 {
298 auto result = _lookup(key);
299 if (result.second) {
300 return result.first->second;
301 }
302 Value value = func(key);
303 _addNew(key, value);
304 return value;
305}

◆ 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.

308 {
309 auto result = _lookup(key);
310 if (result.second) {
311 return result.first->second;
312 }
313 throw LSST_EXCEPT(pex::exceptions::NotFoundError,
314 (boost::format("Unable to find key: %s") % key).str());
315}
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174

◆ 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.

208{ _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.

208{ _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.

161{ 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.

161{ return _container.size(); }

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