proxygen: wangle::LRUPersistentCache< K, V, MutexT

#include <LRUPersistentCache.h>

Inheritance diagram for wangle::LRUPersistentCache< K, V, MutexT >:

Public Types
using	Ptr = std::shared_ptr< LRUPersistentCache< K, V, MutexT >>

Public Member Functions
	LRUPersistentCache (std::size_t cacheCapacity, std::chrono::milliseconds syncInterval=client::persistence::DEFAULT_CACHE_SYNC_INTERVAL, int nSyncRetries=client::persistence::DEFAULT_CACHE_SYNC_RETRIES, std::unique_ptr< CachePersistence< K, V >> persistence=nullptr)

	LRUPersistentCache (std::shared_ptr< folly::Executor > executor, std::size_t cacheCapacity, std::chrono::milliseconds syncInterval, int nSyncRetries, std::unique_ptr< CachePersistence< K, V >> persistence)

	~LRUPersistentCache () override

bool	hasPendingUpdates ()

folly::Optional< V >	get (const K &key) override

void	put (const K &key, const V &val) override

bool	remove (const K &key) override

void	clear (bool clearPersistence=false) override

size_t	size () override

void	setSyncOnDestroy (bool syncOnDestroy)

void	setPersistence (std::unique_ptr< CachePersistence< K, V >> persistence)

Public Member Functions inherited from wangle::PersistentCache< K, V >
virtual	~PersistentCache ()

Private Member Functions
void	setPersistenceHelper (std::unique_ptr< CachePersistence< K, V >> persistence, bool syncVersion) noexcept

CacheDataVersion	load (CachePersistence< K, V > &persistence) noexcept

void	sync ()

void	oneShotSync ()

bool	syncNow (CachePersistence< K, V > &persistence)

std::shared_ptr< CachePersistence< K, V > >	getPersistence ()

Static Private Member Functions
static void *	syncThreadMain (void *arg)

Private Attributes
LRUInMemoryCache< K, V, MutexT >	cache_

bool	stopSyncer_ {false}

std::mutex	stopSyncerMutex_

std::condition_variable	stopSyncerCV_

std::atomic_flag	executorScheduled_ = ATOMIC_FLAG_INIT

const std::chrono::milliseconds	syncInterval_

const int	nSyncRetries_ {client::persistence::DEFAULT_CACHE_SYNC_RETRIES}

int	nSyncTries_ {0}

std::chrono::steady_clock::time_point	lastExecutorScheduleTime_

bool	syncOnDestroy_ {false}

std::shared_ptr< CachePersistence< K, V > >	persistence_

MutexT	persistenceLock_

std::thread	syncer_

std::shared_ptr< folly::Executor >	executor_

Detailed Description

template<typename K, typename V, typename MutexT = std::mutex>
class wangle::LRUPersistentCache< K, V, MutexT >

A PersistentCache implementation that used a CachePersistence for storage. In memory structure fronts the persistence and the cache operations happen on it. Loading from and syncing to persistence are hidden from clients. Sync to persistence happens asynchronously on a separate thread at a configurable interval. Syncs to persistence on destruction as well.

The in memory structure is an EvictingCacheMap which causes this class to evict entries in an LRU fashion.

NOTE NOTE NOTE: Although this class aims to be a cache for arbitrary, it relies heavily on folly::toJson, folly::dynamic and convertTo for serialization and deserialization. So It may not suit your need until true support arbitrary types is written.

Definition at line 119 of file LRUPersistentCache.h.

Member Typedef Documentation

template<typename K, typename V, typename MutexT = std::mutex>

using wangle::LRUPersistentCache< K, V, MutexT >::Ptr = std::shared_ptr<LRUPersistentCache<K, V, MutexT>>

Definition at line 124 of file LRUPersistentCache.h.

Constructor & Destructor Documentation

template<typename K, typename V, typename MutexT >

wangle::LRUPersistentCache< K, V, MutexT >::LRUPersistentCache	(	std::size_t	cacheCapacity,
		std::chrono::milliseconds	syncInterval = `client::persistence::DEFAULT_CACHE_SYNC_INTERVAL`,
		int	nSyncRetries = `client::persistence::DEFAULT_CACHE_SYNC_RETRIES`,
		std::unique_ptr< CachePersistence< K, V >>	persistence = `nullptr`
	)

explicit

LRUPersistentCache constructor

Parameters

cacheCapacity	max number of elements to hold in the cache.
syncInterval	how often to sync to the persistence (in ms).
nSyncRetries	how many times to retry to sync on failure.

Loads the cache and starts of the syncer thread that periodically syncs the cache to persistence.

If persistence is specified, the cache is initially loaded with the contents from it. If load fails, then cache starts empty.

On write failures, the sync will happen again up to nSyncRetries times. Once failed nSyncRetries amount of time, then it will give up and not attempt to sync again until another update occurs.

On reaching capacity limit, LRU items are evicted.

Definition at line 31 of file LRUPersistentCache-inl.h.

     : LRUPersistentCache(
           nullptr,
           cacheCapacity,
           syncInterval,
           nSyncRetries,
           std::move(persistence)) {
 }

template<typename K, typename V, typename MutexT >

wangle::LRUPersistentCache< K, V, MutexT >::LRUPersistentCache	(	std::shared_ptr< folly::Executor >	executor,
		std::size_t	cacheCapacity,
		std::chrono::milliseconds	syncInterval,
		int	nSyncRetries,
		std::unique_ptr< CachePersistence< K, V >>	persistence
	)

Definition at line 45 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::executor_, folly::gen::move, wangle::LRUPersistentCache< K, V, MutexT >::setPersistenceHelper(), and wangle::LRUPersistentCache< K, V, MutexT >::syncer_.

     : cache_(cacheCapacity),
       syncInterval_(syncInterval),
       nSyncRetries_(nSyncRetries),
       executor_(std::move(executor)) {
   // load the cache. be silent if load fails, we just drop the cache
   // and start from scratch.
   if (persistence) {
     setPersistenceHelper(std::move(persistence), true);
   }
   if (!executor_) {
     // start the syncer thread. done at the end of construction so that the
     // cache is fully initialized before being passed to the syncer thread.
     syncer_ =
         std::thread(&LRUPersistentCache<K, V, MutexT>::syncThreadMain, this);
   }
 }

template<typename K , typename V , typename MutexT >

wangle::LRUPersistentCache< K, V, MutexT >::~LRUPersistentCache ( )

override

LRUPersistentCache Destructor

Signals the syncer thread to stop, waits for any pending syncs to be done.

Definition at line 69 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::executor_, folly::detail::lock(), wangle::LRUPersistentCache< K, V, MutexT >::oneShotSync(), wangle::LRUPersistentCache< K, V, MutexT >::stopSyncer_, wangle::LRUPersistentCache< K, V, MutexT >::stopSyncerCV_, wangle::LRUPersistentCache< K, V, MutexT >::stopSyncerMutex_, wangle::LRUPersistentCache< K, V, MutexT >::syncer_, and wangle::LRUPersistentCache< K, V, MutexT >::syncOnDestroy_.

                                                       {
   if (executor_) {
     // In executor mode, each task holds a weak_ptr to the cache itself. No need
     // to notify them the cache is dying. We are done here. Alternatively we may
     // want to do a final sync upon destruction.
     return;
   }
   {
     // tell syncer to wake up and quit
     std::lock_guard<std::mutex> lock(stopSyncerMutex_);
     stopSyncer_ = true;
     if (syncOnDestroy_) {
       // Sync on the thread of the destroyer.
       oneShotSync();
     }
     stopSyncerCV_.notify_all();
   }
   syncer_.join();
 }

Member Function Documentation

template<typename K, typename V, typename MutexT = std::mutex>

void wangle::LRUPersistentCache< K, V, MutexT >::clear ( bool clearPersistence = false )

inlineoverridevirtual

Empty the contents of the cache

Implements wangle::PersistentCache< K, V >.

Definition at line 184 of file LRUPersistentCache.h.

Referenced by wangle::FilePersistentCache< K, V, M >::clear().

                                                      {
     cache_.clear();
     if (clearPersistence) {
       auto persistence = getPersistence();
       if (persistence) {
         persistence->clear();
       }
     }
   }

template<typename K, typename V, typename MutexT = std::mutex>

folly::Optional<V> wangle::LRUPersistentCache< K, V, MutexT >::get ( const K & key )

inlineoverridevirtual

PersistentCache operations

Implements wangle::PersistentCache< K, V >.

Definition at line 174 of file LRUPersistentCache.h.

Referenced by wangle::FilePersistentCache< K, V, M >::get().

                                               {
     return cache_.get(key);
   }

template<typename K , typename V , typename MutexT >

std::shared_ptr< CachePersistence< K, V > > wangle::LRUPersistentCache< K, V, MutexT >::getPersistence ( )

private

Helper to get the persistence layer under lock since it will be called by syncer thread and setters call from any thread.

Definition at line 206 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::persistence_, and wangle::LRUPersistentCache< K, V, MutexT >::persistenceLock_.

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::oneShotSync(), and wangle::LRUPersistentCache< K, V, MutexT >::sync().

                                                  {
   typename wangle::CacheLockGuard<MutexT>::Read readLock(persistenceLock_);
   return persistence_;
 }

template<typename K , typename V , typename MutexT >

bool wangle::LRUPersistentCache< K, V, MutexT >::hasPendingUpdates ( )

Check if there are updates that need to be synced to persistence

Definition at line 112 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_, wangle::LRUPersistentCache< K, V, MutexT >::persistence_, and wangle::LRUPersistentCache< K, V, MutexT >::persistenceLock_.

                                                          {
   typename wangle::CacheLockGuard<MutexT>::Read readLock(persistenceLock_);
   if (!persistence_) {
     return false;
   }
   return cache_.hasChangedSince(persistence_->getLastPersistedVersion());
 }

template<typename K, typename V, typename MutexT >

CacheDataVersion wangle::LRUPersistentCache< K, V, MutexT >::load ( CachePersistence< K, V > & persistence )

privatenoexcept

Load the contents of the persistence passed to constructor in to the in-memory cache. Failure to read will result in no changes to the in-memory data. That is, if in-memory entries exist, and loading fails, the in-memory data remains and will sync down to the underlying persistence layer on the next sync.

Failure to read inclues IO errors and deserialization errors.

Returns: the in memory cache's new version

Definition at line 236 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_.

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::setPersistenceHelper().

                                                   {
   auto kvPairs = persistence.load();
   if (!kvPairs) {
     return false;
   }
   return cache_.loadData(kvPairs.value());
 }

template<typename K , typename V , typename MutexT >

void wangle::LRUPersistentCache< K, V, MutexT >::oneShotSync ( )

private

Definition at line 130 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_, wangle::LRUPersistentCache< K, V, MutexT >::executorScheduled_, wangle::LRUPersistentCache< K, V, MutexT >::getPersistence(), wangle::LRUPersistentCache< K, V, MutexT >::nSyncRetries_, wangle::LRUPersistentCache< K, V, MutexT >::nSyncTries_, and wangle::LRUPersistentCache< K, V, MutexT >::syncNow().

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::~LRUPersistentCache().

                                                    {
   executorScheduled_.clear();
   auto persistence = getPersistence();
   if (persistence && !syncNow(*persistence)) {
     // track failures and give up if we tried too many times
     ++nSyncTries_;
     if (nSyncTries_ == nSyncRetries_) {
       persistence->setPersistedVersion(cache_.getVersion());
       nSyncTries_ = 0;
     }
   } else {
     nSyncTries_ = 0;
   }
 }

template<typename K, typename V, typename MutexT >

void wangle::LRUPersistentCache< K, V, MutexT >::put	(	const K &	key,
		const V &	val
	)

overridevirtual

Set a value corresponding to a key

Parameters

key	string, the key to set
val	string, the value to set

overwrites value if key has a value associated in the cache

Implements wangle::PersistentCache< K, V >.

Definition at line 90 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_, wangle::LRUPersistentCache< K, V, MutexT >::executor_, wangle::LRUPersistentCache< K, V, MutexT >::executorScheduled_, wangle::LRUPersistentCache< K, V, MutexT >::lastExecutorScheduleTime_, folly::detail::lock(), folly::gen::move, now(), and wangle::LRUPersistentCache< K, V, MutexT >::syncInterval_.

Referenced by wangle::FilePersistentCache< K, V, M >::put().

                                                                      {
   cache_.put(key, val);
   if (executor_) {
     if (!executorScheduled_.test_and_set()) {
       if (std::chrono::steady_clock::now() - lastExecutorScheduleTime_ <
           syncInterval_) {
         // Do not schedule more than once during a syncInterval_ period
         return;
       }
       std::weak_ptr<LRUPersistentCache<K, V, MutexT>> weakSelf =
           this->shared_from_this();
       lastExecutorScheduleTime_ = std::chrono::steady_clock::now();
       executor_->add([self = std::move(weakSelf)]() {
         if (auto sharedSelf = self.lock()) {
           sharedSelf->oneShotSync();
         }
       });
     }
   }
 }

template<typename K, typename V, typename MutexT = std::mutex>

bool wangle::LRUPersistentCache< K, V, MutexT >::remove ( const K & key )

inlineoverridevirtual

Clear a cache entry associated with a key

Parameters

key	string, the key to lookup and clear

Returns: boolean true if any elements are removed, else false

Implements wangle::PersistentCache< K, V >.

Definition at line 180 of file LRUPersistentCache.h.

Referenced by wangle::FilePersistentCache< K, V, M >::remove().

                                      {
     return cache_.remove(key);
   }

template<typename K, typename V, typename MutexT >

void wangle::LRUPersistentCache< K, V, MutexT >::setPersistence ( std::unique_ptr< CachePersistence< K, V >> persistence )

Set a new persistence layer on this cache. This call blocks while the new persistence layer is loaded into the cache. The load is also done under a lock so multiple calls to this will not stomp on each other.

Definition at line 227 of file LRUPersistentCache-inl.h.

References folly::gen::move, and wangle::LRUPersistentCache< K, V, MutexT >::setPersistenceHelper().

                                                        {
   // note that we don't set the persisted version on the persistence like we
   // do in the constructor since we want any deltas that were in memory but
   // not in the persistence layer to sync back.
   setPersistenceHelper(std::move(persistence), false);
 }

template<typename K, typename V, typename MutexT >

void wangle::LRUPersistentCache< K, V, MutexT >::setPersistenceHelper	(	std::unique_ptr< CachePersistence< K, V >>	persistence,
		bool	syncVersion
	)

privatenoexcept

Helper to set persistence that will load the persistence data into memory and optionally sync versions

Definition at line 212 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::load(), folly::gen::move, wangle::LRUPersistentCache< K, V, MutexT >::persistence_, wangle::LRUPersistentCache< K, V, MutexT >::persistenceLock_, and version.

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::LRUPersistentCache(), and wangle::LRUPersistentCache< K, V, MutexT >::setPersistence().

                                {
   typename wangle::CacheLockGuard<MutexT>::Write writeLock(persistenceLock_);
   persistence_ = std::move(persistence);
   // load the persistence data into memory
   if (persistence_) {
     auto version = load(*persistence_);
     if (syncVersion) {
       persistence_->setPersistedVersion(version);
     }
   }
 }

template<typename K, typename V, typename MutexT = std::mutex>

void wangle::LRUPersistentCache< K, V, MutexT >::setSyncOnDestroy ( bool syncOnDestroy )

inline

Definition at line 198 of file LRUPersistentCache.h.

Referenced by wangle::FilePersistentCache< K, V, M >::setSyncOnDestroy().

                                             {
     syncOnDestroy_ = syncOnDestroy;
   }

template<typename K, typename V, typename MutexT = std::mutex>

size_t wangle::LRUPersistentCache< K, V, MutexT >::size ( )

inlineoverridevirtual

return the size of the cache

Returns: size_t, the size of the cache

Implements wangle::PersistentCache< K, V >.

Definition at line 194 of file LRUPersistentCache.h.

Referenced by wangle::FilePersistentCache< K, V, M >::size().

                          {
     return cache_.size();
   }

template<typename K , typename V , typename MutexT >

void wangle::LRUPersistentCache< K, V, MutexT >::sync ( )

private

The syncer thread's function. Syncs to the persistence, if necessary, after every syncInterval_ seconds.

Definition at line 146 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_, wangle::LRUPersistentCache< K, V, MutexT >::getPersistence(), wangle::LRUPersistentCache< K, V, MutexT >::nSyncRetries_, wangle::LRUPersistentCache< K, V, MutexT >::stopSyncer_, wangle::LRUPersistentCache< K, V, MutexT >::stopSyncerCV_, wangle::LRUPersistentCache< K, V, MutexT >::stopSyncerMutex_, wangle::LRUPersistentCache< K, V, MutexT >::syncInterval_, and wangle::LRUPersistentCache< K, V, MutexT >::syncNow().

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::syncThreadMain().

                                             {
   // keep running as long the destructor signals to stop or
   // there are pending updates that are not synced yet
   std::unique_lock<std::mutex> stopSyncerLock(stopSyncerMutex_);
   int nSyncFailures = 0;
   while (true) {
     auto persistence = getPersistence();
     if (stopSyncer_) {
       if (!persistence ||
           !cache_.hasChangedSince(persistence->getLastPersistedVersion())) {
         break;
       }
     }
 
     if (persistence && !syncNow(*persistence)) {
       // track failures and give up if we tried too many times
       ++nSyncFailures;
       if (nSyncFailures == nSyncRetries_) {
         persistence->setPersistedVersion(cache_.getVersion());
         nSyncFailures = 0;
       }
     } else {
       nSyncFailures = 0;
     }
 
     if (!stopSyncer_) {
       stopSyncerCV_.wait_for(stopSyncerLock, syncInterval_);
     }
   }
 }

template<typename K, typename V, typename MutexT >

bool wangle::LRUPersistentCache< K, V, MutexT >::syncNow ( CachePersistence< K, V > & persistence )

private

Helper to sync routine above that actualy does the serialization and writes to persistence.

Returns: boolean, true on successful serialization and write to persistence, false otherwise

Definition at line 178 of file LRUPersistentCache-inl.h.

References wangle::LRUPersistentCache< K, V, MutexT >::cache_, wangle::CachePersistence< K, V >::getLastPersistedVersion(), folly::gen::move, wangle::CachePersistence< K, V >::persistVersionedData(), and version.

Referenced by wangle::LRUPersistentCache< K, V, MutexT >::oneShotSync(), and wangle::LRUPersistentCache< K, V, MutexT >::sync().

                                           {
   // check if we need to sync.  There is a chance that someone can
   // update cache_ between this check and the convert below, but that
   // is ok.  The persistence layer would have needed to update anyway
   // and will just get the latest version.
   if (!cache_.hasChangedSince(persistence.getLastPersistedVersion())) {
     // nothing to do
     return true;
   }
 
   // serialize the current contents of cache under lock
   auto serializedCacheAndVersion = cache_.convertToKeyValuePairs();
   if (!serializedCacheAndVersion) {
     LOG(ERROR) << "Failed to convert cache for serialization.";
     return false;
   }
 
   auto& kvPairs = std::get<0>(serializedCacheAndVersion.value());
   auto& version = std::get<1>(serializedCacheAndVersion.value());
   auto persisted =
     persistence.persistVersionedData(std::move(kvPairs), version);
 
   return persisted;
 }

template<typename K , typename V , typename MutexT >

void * wangle::LRUPersistentCache< K, V, MutexT >::syncThreadMain ( void * arg )

staticprivate

Definition at line 121 of file LRUPersistentCache-inl.h.

References folly::setThreadName(), and wangle::LRUPersistentCache< K, V, MutexT >::sync().

                                                                 {
   folly::setThreadName("lru-sync-thread");
 
   auto self = static_cast<LRUPersistentCache<K, V, MutexT>*>(arg);
   self->sync();
   return nullptr;
 }