730 lines
29 KiB
C++
730 lines
29 KiB
C++
/**
|
|
* @file include/ActivMiddleware/Misc/LazyThreadSpecificCache.h
|
|
*
|
|
* @brief A thread specific cache which can "lazily" check for an updated mutex-protected master version and copy to thread
|
|
* specific storage. Single-value and vector caches are provided.
|
|
*/
|
|
|
|
#if (!defined ACTIV_MIDDLEWARE_MISC_LAZY_THREAD_SPECIFIC_CACHE_H)
|
|
#define ACTIV_MIDDLEWARE_MISC_LAZY_THREAD_SPECIFIC_CACHE_H
|
|
|
|
#include "ActivMiddleware/ActivBase/MutexHelper.h"
|
|
#include "ActivMiddleware/CxxYZ/atomic.h"
|
|
|
|
//! Activ namespace.
|
|
namespace Activ
|
|
{
|
|
|
|
// Forward references.
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheBase;
|
|
|
|
template<typename TAG, typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheTagBase;
|
|
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCache;
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Tag to pass to LazyThreadSpecificCacheTypes to specify a single-value cache.
|
|
class LazyThreadSpecificCacheTag;
|
|
|
|
//! Tag to pass to LazyThreadSpecificCacheTypes to specify a vector cache.
|
|
class LazyThreadSpecificVectorCacheTag;
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
namespace LazyThreadSpecificCacheDetail
|
|
{
|
|
|
|
template<typename TAG, typename VERSIONED_SHARED_TYPE, typename VERSIONED_THREAD_SPECIFIC_TYPE>
|
|
class StorageTypes
|
|
{
|
|
};
|
|
|
|
template<typename VERSIONED_SHARED_TYPE, typename VERSIONED_THREAD_SPECIFIC_TYPE>
|
|
class StorageTypes<LazyThreadSpecificCacheTag, VERSIONED_SHARED_TYPE, VERSIONED_THREAD_SPECIFIC_TYPE>
|
|
{
|
|
public:
|
|
typedef VERSIONED_SHARED_TYPE SharedStorageType;
|
|
typedef VERSIONED_THREAD_SPECIFIC_TYPE ThreadSpecificStorageType;
|
|
};
|
|
|
|
template<typename VERSIONED_SHARED_TYPE, typename VERSIONED_THREAD_SPECIFIC_TYPE>
|
|
class StorageTypes<LazyThreadSpecificVectorCacheTag, VERSIONED_SHARED_TYPE, VERSIONED_THREAD_SPECIFIC_TYPE>
|
|
{
|
|
public:
|
|
typedef CxxYZ::vector<VERSIONED_SHARED_TYPE> SharedStorageType;
|
|
typedef CxxYZ::vector<VERSIONED_THREAD_SPECIFIC_TYPE> ThreadSpecificStorageType;
|
|
};
|
|
|
|
} // namespace LazyThreadSpecificCacheDetail
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Template defining the types to be stored in the cache.
|
|
*
|
|
* @tparam TAG LazyThreadSpecificCacheTag for a single-value cache; LazyThreadSpecificVectorCacheTag for a vector.
|
|
* @tparam SHARED_TYPE the type that will be shared amongst threads.
|
|
* @tparam THREAD_SPECIFIC_TYPE the type that will be stored in thread-specific storage.
|
|
*
|
|
* SHARED_TYPE and THREAD_SPECIFIC_TYPE can be different if, for example, you wish the thread-specific copy to
|
|
* contain additional members derived from common members which can be created at the point the thread-specific
|
|
* version is updated from the shared master.
|
|
*/
|
|
template<typename TAG, typename SHARED_TYPE, typename THREAD_SPECIFIC_TYPE = SHARED_TYPE>
|
|
class LazyThreadSpecificCacheTypes
|
|
{
|
|
public:
|
|
typedef TAG Tag;
|
|
|
|
private:
|
|
typedef SHARED_TYPE SharedType;
|
|
typedef THREAD_SPECIFIC_TYPE ThreadSpecificType;
|
|
|
|
//! Actual data stored is the provided type and a version.
|
|
template<typename T>
|
|
class VersionedType
|
|
{
|
|
public:
|
|
VersionedType() :
|
|
m_version(0)
|
|
{
|
|
}
|
|
|
|
VersionedType(ACTIV_BOOST_RV_REF(VersionedType<T>) versionedType) :
|
|
m_value(CxxYZ::move(versionedType.m_value)),
|
|
m_version(versionedType.m_version)
|
|
{
|
|
}
|
|
|
|
VersionedType &operator=(ACTIV_BOOST_RV_REF(VersionedType<T>) rhs)
|
|
{
|
|
if (this != &rhs)
|
|
{
|
|
m_value = CxxYZ::move(rhs.m_value);
|
|
m_version = rhs.m_version;
|
|
}
|
|
|
|
return *this;
|
|
}
|
|
|
|
T m_value;
|
|
uint64_t m_version;
|
|
|
|
private:
|
|
ACTIV_BOOST_MOVABLE_BUT_NOT_COPYABLE(VersionedType)
|
|
};
|
|
|
|
//! The provided SHARED_TYPE plus a version.
|
|
typedef VersionedType<SharedType> VersionedSharedType;
|
|
|
|
//! The provided THREAD_SPECIFIC_TYPE plus a version.
|
|
typedef VersionedType<ThreadSpecificType> VersionedThreadSpecificType;
|
|
|
|
/**
|
|
* @brief The shared type (VersionedSharedType for LazyThreadSpecificCacheTag,
|
|
* CxxYZ::vector<VersionedSharedType> for LazyThreadSpecificVectorCacheTag) we store.
|
|
*/
|
|
typedef typename LazyThreadSpecificCacheDetail::StorageTypes<Tag, VersionedSharedType,
|
|
VersionedThreadSpecificType>::SharedStorageType SharedStorageType;
|
|
|
|
public:
|
|
/**
|
|
* @brief The thread-specific type (VersionedThreadSpecificType for LazyThreadSpecificCacheTag,
|
|
* CxxYZ::vector<VersionedThreadSpecificType> for LazyThreadSpecificVectorCacheTag) we store.
|
|
*/
|
|
typedef typename LazyThreadSpecificCacheDetail::StorageTypes<Tag, VersionedSharedType,
|
|
VersionedThreadSpecificType>::ThreadSpecificStorageType ThreadSpecificStorageType;
|
|
|
|
template<typename, typename, typename>
|
|
friend class LazyThreadSpecificCacheBase;
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Common base for cache.
|
|
*
|
|
* @tparam DERIVED the class derived from LazyThreadSpecificCache.
|
|
* @tparam TYPES LazyThreadSpecificCacheTypes defining the shared and thread-specific types to be stored.
|
|
* @tparam THREAD_SPECIFIC_DATA the ThreadSpecificData type that will be storing the thread-specific data.
|
|
*/
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheBase
|
|
{
|
|
private:
|
|
typedef typename TYPES::Tag Tag;
|
|
|
|
protected:
|
|
typedef typename TYPES::SharedType SharedType;
|
|
typedef typename TYPES::ThreadSpecificType ThreadSpecificType;
|
|
|
|
typedef typename TYPES::VersionedSharedType VersionedSharedType;
|
|
typedef typename TYPES::VersionedThreadSpecificType VersionedThreadSpecificType;
|
|
|
|
typedef typename TYPES::SharedStorageType SharedStorageType;
|
|
typedef typename TYPES::ThreadSpecificStorageType ThreadSpecificStorageType;
|
|
|
|
//! Return values for CreateSharedValue().
|
|
enum CreateSharedValueResult
|
|
{
|
|
CREATE_SHARED_VALUE_RESULT_SUCCESS, //! sharedValue was successfully populated.
|
|
CREATE_SHARED_VALUE_NOOP_KEEP_STALE, //! sharedValue was not successfully populated. Do not reset staleness.
|
|
CREATE_SHARED_VALUE_NOOP_RESET_STALE //! sharedValue was not successfully populated. Do reset staleness.
|
|
};
|
|
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param pMutex mutex over the shared data.
|
|
* @param threadSpecificData reference to a ThreadSpecificData object handling thread-specific storage.
|
|
*/
|
|
LazyThreadSpecificCacheBase(IMutex * const pMutex, THREAD_SPECIFIC_DATA &threadSpecificData) :
|
|
m_pMutex(pMutex),
|
|
m_threadSpecificData(threadSpecificData),
|
|
m_lastStaleVersion(0)
|
|
{
|
|
}
|
|
|
|
//! Mark the cache as stale such that the next thread that calls Get() will update the shared copy.
|
|
void SetStale()
|
|
{
|
|
m_lastStaleVersion.fetch_add(1);
|
|
}
|
|
|
|
protected:
|
|
void UpdateSharedValue(SharedType ¤tSharedValue, SharedType &newSharedValue)
|
|
{
|
|
// Default implementation: move.
|
|
#if (!defined ACTIV_BOOST_NO_CXX11_RVALUE_REFERENCES)
|
|
currentSharedValue = CxxYZ::move(newSharedValue);
|
|
#else
|
|
currentSharedValue = newSharedValue;
|
|
#endif
|
|
}
|
|
|
|
void UpdateThreadSpecificValue(const SharedType &sharedValue, ThreadSpecificType &threadSpecificValue)
|
|
{
|
|
// Default implementation: copy.
|
|
threadSpecificValue = sharedValue;
|
|
}
|
|
|
|
private:
|
|
/**
|
|
* @brief The calling thread has no thread-specific storage; create it.
|
|
*
|
|
* @return A new THREAD_SPECIFIC_DATA::Type pointer.
|
|
*/
|
|
typename THREAD_SPECIFIC_DATA::Type *CreateThreadSpecificData()
|
|
{
|
|
typename THREAD_SPECIFIC_DATA::Type * const pThreadSpecificData = new typename THREAD_SPECIFIC_DATA::Type;
|
|
|
|
m_threadSpecificData.Set(pThreadSpecificData);
|
|
return pThreadSpecificData;
|
|
}
|
|
|
|
/**
|
|
* @brief Common code to update shared and thread-specific values.
|
|
*
|
|
* @param initialSharedVersion
|
|
* @param createSharedValueResult
|
|
* @param versionedSharedValue
|
|
* @param newSharedValue
|
|
* @param versionedThreadSpecificValue
|
|
*/
|
|
void CommonUpdate(const uint64_t initialSharedVersion, const CreateSharedValueResult createSharedValueResult,
|
|
VersionedSharedType &versionedSharedValue, SharedType &newSharedValue,
|
|
VersionedThreadSpecificType &versionedThreadSpecificValue)
|
|
{
|
|
// Another thread may have got in before us and already updated the shared value.
|
|
// Leave it to the derived class to decide which one is the best one to use in that case.
|
|
const bool shouldUpdateSharedValue((initialSharedVersion == versionedSharedValue.m_version) ||
|
|
this->GetDerived().ShouldUpdateSharedValue(versionedSharedValue.m_value, newSharedValue));
|
|
|
|
if (shouldUpdateSharedValue)
|
|
{
|
|
switch (createSharedValueResult)
|
|
{
|
|
// Move new value to shared.
|
|
case CREATE_SHARED_VALUE_RESULT_SUCCESS:
|
|
this->GetDerived().UpdateSharedValue(versionedSharedValue.m_value, newSharedValue);
|
|
versionedSharedValue.m_version = m_lastStaleVersion + 1;
|
|
break;
|
|
|
|
// Do nothing.
|
|
case CREATE_SHARED_VALUE_NOOP_KEEP_STALE:
|
|
break;
|
|
|
|
// Just clear down staleness.
|
|
case CREATE_SHARED_VALUE_NOOP_RESET_STALE:
|
|
versionedSharedValue.m_version = m_lastStaleVersion + 1;
|
|
break;
|
|
|
|
default:
|
|
break;
|
|
}
|
|
}
|
|
|
|
// Update the thread specific copy?
|
|
if (versionedSharedValue.m_version != versionedThreadSpecificValue.m_version)
|
|
{
|
|
this->GetDerived().UpdateThreadSpecificValue(versionedSharedValue.m_value, versionedThreadSpecificValue.m_value);
|
|
versionedThreadSpecificValue.m_version = versionedSharedValue.m_version;
|
|
}
|
|
}
|
|
|
|
DERIVED &GetDerived()
|
|
{
|
|
return static_cast<DERIVED &>(*this);
|
|
}
|
|
|
|
IMutex * const m_pMutex;
|
|
THREAD_SPECIFIC_DATA & m_threadSpecificData;
|
|
|
|
CxxYZ::atomic<uint64_t> m_lastStaleVersion;
|
|
SharedStorageType m_sharedStorage;
|
|
|
|
template<typename, typename, typename, typename>
|
|
friend class LazyThreadSpecificCacheTagBase;
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
template<typename TAG, typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheTagBase
|
|
{
|
|
// No implementation.
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Base for single-value cache.
|
|
*
|
|
* The derived class needs to provide the following methods:
|
|
*
|
|
* ThreadSpecificStorageType &GetThreadSpecificStorage(THREAD_SPECIFIC_DATA::Type &threadSpecificInfo);
|
|
* CreateSharedValueResult CreateSharedValue(SharedType &sharedValue);
|
|
* bool ShouldUpdateSharedValue(const SharedType ¤tSharedValue, const SharedType &newSharedValue) const;
|
|
*
|
|
* These are optional:
|
|
*
|
|
* void UpdateSharedValue(SharedType ¤tSharedValue, SharedType &newSharedValue);
|
|
* void UpdateThreadSpecificValue(const SharedType &sharedValue, ThreadSpecificType &threadSpecificValue);
|
|
*
|
|
*
|
|
* GetThreadSpecificStorage():
|
|
*
|
|
* The cache is de-coupled from the ThreadSpecificStorage instance used to store thread-specific data. This is such that
|
|
* multiple caches may be used with one ThreadSpecificStorage, avoiding incurring the cost of one thread-specific slot for
|
|
* each cache that is used. Similarly, the class does not provide a mutex for protecting the shared copy of the data -
|
|
* one must be passed to the constructor (again so one mutex can protect multiple cache shared values).
|
|
* GetThreadSpecificStorage() is used to retrieve the correct thread-specific storage from the
|
|
* the THREAD_SPECIFIC_DATA passed to the constructor.
|
|
*
|
|
*
|
|
* CreateSharedValue():
|
|
*
|
|
* When Get() is first called, or Get() is later called after a call to SetStale(), the shared copy of the data will need
|
|
* to be updated. This shared version is then copied to the calling thread. The derived class must provide a function to
|
|
* create a new SHARED_TYPE instance. Note the mutex is not held when this function is called; the new shared value is not
|
|
* actually copied to shared storage until UpdateSharedValue() is called (see below).
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_RESULT_SUCCESS to indicate the sharedValue reference has been populated,
|
|
* in which case the UpdateSharedValue() function will be called with the mutex locked.
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_NOOP_RESET_STALE to indicate no change to the shared state is required,
|
|
* and thread-local copies should just be updated from the shared copies. The shared state is marked as no longer stale sucj
|
|
* that the next call to Get() will not invoke CreateSharedValue() again (unless SetStale() has been called).
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_NOOP_KEEP_STALE to indicate the creating the new shared value failed and that the
|
|
* staleness should remain set (the next call to Get() will again call CreateSharedValue()).
|
|
*
|
|
* Note any exception thrown within CreateSharedValue() will propogate to the caller.
|
|
*
|
|
*
|
|
* ShouldUpdateSharedValue():
|
|
*
|
|
* If two threads happened to call Get() at approximately the same time, it may be that a decision needs to be made about
|
|
* whether the result from CreateSharedValue() should be used at all.
|
|
*
|
|
* It is called with the mutex locked and is passed the current shared value and the one we just returned from CreateSharedValue().
|
|
*
|
|
*
|
|
* UpdateSharedValue():
|
|
*
|
|
* Once a new SharedType instance has been populated, the shared copy must be updated. This method should copy or move the
|
|
* parameter newSharedValue to currentSharedValue (std::swap, for instance - this is why newSharedValue is passed
|
|
* by non-const reference). A default implementation is provided that does:
|
|
*
|
|
* currentSharedValue = CxxYZ::move(newSharedValue);
|
|
*
|
|
*
|
|
* UpdateThreadSpecificValue():
|
|
*
|
|
* Finally, the thread calling Get() must have its thread-specific copy updated. The mutex is still held at this point.
|
|
* Generally an implementation of this will just do something like:
|
|
*
|
|
* threadSpecificValue = sharedValue;
|
|
*
|
|
* However, the populating of additional thread-specific members of THREAD_SPECIFIC_TYPE should be done here (see
|
|
* LazyThreadSpecificCacheTypes description). A default implementation is provided that does:
|
|
*
|
|
* threadSpecificValue = sharedValue;
|
|
*
|
|
* @tparam DERIVED the class derived from LazyThreadSpecificCache.
|
|
* @tparam TYPES LazyThreadSpecificCacheTypes defining the shared and thread-specific types to be stored.
|
|
* @tparam THREAD_SPECIFIC_DATA the ThreadSpecificData type that will be storing the thread-specific data.
|
|
*/
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheTagBase<LazyThreadSpecificCacheTag, DERIVED, TYPES, THREAD_SPECIFIC_DATA> : public
|
|
LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA>
|
|
{
|
|
protected:
|
|
typedef LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA> Base;
|
|
|
|
typedef typename Base::SharedType SharedType;
|
|
typedef typename Base::ThreadSpecificType ThreadSpecificType;
|
|
|
|
typedef typename Base::VersionedSharedType VersionedSharedType;
|
|
typedef typename Base::VersionedThreadSpecificType VersionedThreadSpecificType;
|
|
|
|
typedef typename Base::SharedStorageType SharedStorageType;
|
|
typedef typename Base::ThreadSpecificStorageType ThreadSpecificStorageType;
|
|
|
|
typedef typename Base::CreateSharedValueResult CreateSharedValueResult;
|
|
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param pMutex mutex over the shared data.
|
|
* @param threadSpecificData reference to a ThreadSpecificData object handling thread-specific storage.
|
|
*/
|
|
LazyThreadSpecificCacheTagBase(IMutex * const pMutex, THREAD_SPECIFIC_DATA &threadSpecificData) :
|
|
LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA>(pMutex, threadSpecificData)
|
|
{
|
|
}
|
|
|
|
/**
|
|
* @brief Get a reference to thread-specific copy of the data.
|
|
*
|
|
* If the cache has been marked as stale and no other thread has yet rebuilt the master shared copy of the data,
|
|
* DERIVED::CreateSharedValue() is invoked followed by DERIVED::UpdateSharedValue().
|
|
*
|
|
* If the shared copy is newer than this thread's copy, or we've just had DERIVED::CreateSharedValue() called,
|
|
* DERIVED::UpdateThreadSpecificValue() is invoked.
|
|
*
|
|
* @return The thread-specific value for this thread.
|
|
*/
|
|
const ThreadSpecificType &Get()
|
|
{
|
|
typename THREAD_SPECIFIC_DATA::Type *pThreadSpecificData = this->m_threadSpecificData.Get();
|
|
if (ACTIV_UNLIKELY(0 == pThreadSpecificData))
|
|
pThreadSpecificData = this->CreateThreadSpecificData();
|
|
|
|
VersionedThreadSpecificType &versionedThreadSpecificValue(
|
|
this->GetDerived().GetThreadSpecificStorage(*pThreadSpecificData));
|
|
|
|
// Check if the shared version has been updated. Obviously we're not locking the mutex just to read these, but if the
|
|
// thread-local copy doesn't get updated "for a while", it doesn't matter too much (it's lazy, after all).
|
|
if (ACTIV_UNLIKELY(versionedThreadSpecificValue.m_version <= this->m_lastStaleVersion))
|
|
Update(versionedThreadSpecificValue);
|
|
|
|
return versionedThreadSpecificValue.m_value;
|
|
}
|
|
|
|
/**
|
|
* @brief Get a mutable reference to the shared type. This should only be called if the mutex has been locked,
|
|
* and should probably follow or preceed a SetStale() for sane behaviour.
|
|
*
|
|
* @return Reference to the stored shared type.
|
|
*/
|
|
SharedType &GetSharedValue()
|
|
{
|
|
return this->m_sharedStorage.m_value;
|
|
}
|
|
|
|
/**
|
|
* @brief Get a const reference to the shared type. This should only be called if the mutex has been locked.
|
|
*
|
|
* @return Reference to the stored shared type.
|
|
*/
|
|
const SharedType &GetSharedValue() const
|
|
{
|
|
return this->m_sharedStorage.m_value;
|
|
}
|
|
|
|
private:
|
|
/**
|
|
* @brief Update this thread's and possibly the shared value.
|
|
*
|
|
* @param threadSpecificValue storage for the calling thread.
|
|
*/
|
|
void Update(VersionedThreadSpecificType &versionedThreadSpecificValue)
|
|
{
|
|
SharedType newSharedValue;
|
|
CreateSharedValueResult createSharedValueResult = Base::CREATE_SHARED_VALUE_NOOP_KEEP_STALE;
|
|
const uint64_t initialSharedVersion = this->m_sharedStorage.m_version;
|
|
|
|
if (initialSharedVersion <= this->m_lastStaleVersion)
|
|
{
|
|
// Note we are not calling this with the mutex held. Multiple threads calling Get() at the same time may
|
|
// therefore invoke CreateSharedValue(); this is OK as the shared copy is then updated with the mutex held.
|
|
createSharedValueResult = this->GetDerived().CreateSharedValue(newSharedValue);
|
|
}
|
|
|
|
{
|
|
ScopedMutexLocker scopedMutexLocker(this->m_pMutex);
|
|
|
|
this->CommonUpdate(initialSharedVersion, createSharedValueResult, this->m_sharedStorage, newSharedValue,
|
|
versionedThreadSpecificValue);
|
|
}
|
|
}
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Base for vector cache.
|
|
*
|
|
* The derived class needs to provide the following methods:
|
|
*
|
|
* ThreadSpecificStorage &GetThreadSpecificStorage(THREAD_SPECIFIC_DATA::Type &threadSpecificInfo, const T &context);
|
|
* CreateSharedValueResult CreateSharedValue(SharedType &sharedValue, const T &context);
|
|
* bool ShouldUpdateSharedValue(const SharedType ¤tSharedValue, const SharedType &newSharedValue) const;
|
|
*
|
|
* These are optional:
|
|
*
|
|
* void UpdateSharedValue(SharedType ¤tSharedValue, SharedType &newSharedValue);
|
|
* void UpdateThreadSpecificValue(const SharedType &sharedValue, ThreadSpecificType &threadSpecificValue);
|
|
*
|
|
*
|
|
* GetThreadSpecificStorage():
|
|
*
|
|
* The cache is de-coupled from the ThreadSpecificStorage instance used to store thread-specific data. This is such that
|
|
* multiple caches may be used with one ThreadSpecificStorage, avoiding incurring the cost of one thread-specific slot for
|
|
* each cache that is used. Similarly, the class does not provide a mutex for protecting the shared copy of the data -
|
|
* one must be passed to the constructor (again so one mutex can protect multiple cache shared values).
|
|
* GetThreadSpecificStorage() is used to retrieve the correct thread-specific storage from the
|
|
* the THREAD_SPECIFIC_DATA passed to the constructor. The context passed to Get() is provided as the second parameter.
|
|
*
|
|
*
|
|
* CreateSharedValue():
|
|
*
|
|
* When Get() is first called, or Get() is later called after a call to SetStale(), the shared copy of the data will need
|
|
* to be updated. This shared version is then copied to the calling thread. The derived class must provide a function to
|
|
* create a new SHARED_TYPE instance. Note the mutex is not held when this function is called; the new shared value is not
|
|
* actually copied to shared storage until UpdateSharedValue() is called (see below).
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_RESULT_SUCCESS to indicate the sharedValue reference has been populated,
|
|
* in which case the UpdateSharedValue() function will be called with the mutex locked.
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_NOOP_RESET_STALE to indicate no change to the shared state is required,
|
|
* and thread-local copies should just be updated from the shared copies. The shared state is marked as no longer stale sucj
|
|
* that the next call to Get() will not invoke CreateSharedValue() again (unless SetStale() has been called).
|
|
*
|
|
* It can return CREATE_SHARED_VALUE_NOOP_KEEP_STALE to indicate the creating the new shared value failed and that the
|
|
* staleness should remain set (the next call to Get() will again call CreateSharedValue()).
|
|
*
|
|
* Note any exception thrown within CreateSharedValue() will propogate to the caller.
|
|
*
|
|
* The context passed to Get() is provided as the second parameter.
|
|
*
|
|
*
|
|
* ShouldUpdateSharedValue():
|
|
*
|
|
* If two threads happened to call Get() at approximately the same time, it may be that a decision needs to be made about
|
|
* whether the result from CreateSharedValue() should be used at all.
|
|
*
|
|
* It is called with the mutex locked and is passed the current shared value and the one we just returned from CreateSharedValue().
|
|
*
|
|
*
|
|
* UpdateSharedValue():
|
|
*
|
|
* Once a new SharedType instance has been populated, the shared copy must be updated. This method should copy or move the
|
|
* parameter newSharedValue to currentSharedValue (std::swap, for instance - this is why newSharedValue is passed
|
|
* by non-const reference). A default implementation is provided that does:
|
|
*
|
|
* currentSharedValue = CxxYZ::move(newSharedValue);
|
|
*
|
|
*
|
|
* UpdateThreadSpecificValue():
|
|
*
|
|
* Finally, the thread calling Get() must have its thread-specific copy updated. The mutex is still held at this point.
|
|
* Generally an implementation of this will just do something like:
|
|
*
|
|
* threadSpecificValue = sharedValue;
|
|
*
|
|
* However, the populating of additional thread-specific members of THREAD_SPECIFIC_TYPE should be done here (see
|
|
* LazyThreadSpecificCacheTypes description). A default implementation is provided that does:
|
|
*
|
|
* threadSpecificValue = sharedValue;
|
|
*
|
|
* @tparam DERIVED the class derived from LazyThreadSpecificCache.
|
|
* @tparam TYPES LazyThreadSpecificCacheTypes defining the shared and thread-specific types to be stored.
|
|
* @tparam THREAD_SPECIFIC_DATA the ThreadSpecificData type that will be storing the thread-specific data.
|
|
*/
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCacheTagBase<LazyThreadSpecificVectorCacheTag, DERIVED, TYPES, THREAD_SPECIFIC_DATA> : public
|
|
LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA>
|
|
{
|
|
protected:
|
|
typedef LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA> Base;
|
|
|
|
typedef typename Base::SharedType SharedType;
|
|
typedef typename Base::ThreadSpecificType ThreadSpecificType;
|
|
|
|
typedef typename Base::VersionedSharedType VersionedSharedType;
|
|
typedef typename Base::VersionedThreadSpecificType VersionedThreadSpecificType;
|
|
|
|
typedef typename Base::SharedStorageType SharedStorageType;
|
|
typedef typename Base::ThreadSpecificStorageType ThreadSpecificStorageType;
|
|
|
|
typedef typename Base::CreateSharedValueResult CreateSharedValueResult;
|
|
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param pMutex mutex over the shared data.
|
|
* @param threadSpecificData reference to a ThreadSpecificData object handling thread-specific storage.
|
|
*/
|
|
LazyThreadSpecificCacheTagBase(IMutex * const pMutex, THREAD_SPECIFIC_DATA &threadSpecificData) :
|
|
LazyThreadSpecificCacheBase<DERIVED, TYPES, THREAD_SPECIFIC_DATA>(pMutex, threadSpecificData)
|
|
{
|
|
}
|
|
|
|
//! Get a reference to thread-specific copy of the data.
|
|
template<typename T>
|
|
const ThreadSpecificType &Get(const size_t index, const T &context)
|
|
{
|
|
typename THREAD_SPECIFIC_DATA::Type *pThreadSpecificData = this->m_threadSpecificData.Get();
|
|
if (ACTIV_UNLIKELY(0 == pThreadSpecificData))
|
|
pThreadSpecificData = this->CreateThreadSpecificData();
|
|
|
|
ThreadSpecificStorageType &threadSpecificStorage(
|
|
this->GetDerived().GetThreadSpecificStorage(*pThreadSpecificData, context));
|
|
|
|
bool shouldUpdateThreadSpecificCopy = false;
|
|
VersionedThreadSpecificType *pVersionedThreadSpecificValue;
|
|
|
|
if (ACTIV_LIKELY(index < threadSpecificStorage.size()))
|
|
{
|
|
pVersionedThreadSpecificValue = &threadSpecificStorage[index];
|
|
|
|
if (ACTIV_UNLIKELY(pVersionedThreadSpecificValue->m_version <= this->m_lastStaleVersion))
|
|
shouldUpdateThreadSpecificCopy = true;
|
|
}
|
|
else
|
|
{
|
|
shouldUpdateThreadSpecificCopy = true;
|
|
threadSpecificStorage.resize(index + 1);
|
|
pVersionedThreadSpecificValue = &threadSpecificStorage[index];
|
|
}
|
|
|
|
VersionedThreadSpecificType &versionedThreadSpecificValue(*pVersionedThreadSpecificValue);
|
|
|
|
if (ACTIV_UNLIKELY(shouldUpdateThreadSpecificCopy))
|
|
Update(versionedThreadSpecificValue, index, context);
|
|
|
|
return versionedThreadSpecificValue.m_value;
|
|
}
|
|
|
|
/**
|
|
* @brief Mark the cache as stale and also clear the shared vector.
|
|
*
|
|
* NB it is the user's responsibility to lock the mutex before calling this function. It is not done here such
|
|
* that batch work can be done with the mutex held.
|
|
*/
|
|
void Clear()
|
|
{
|
|
this->m_sharedStorage.clear();
|
|
this->SetStale();
|
|
}
|
|
|
|
private:
|
|
/**
|
|
* @brief Update this thread's and possibly the shared value.
|
|
*
|
|
* @param versionedThreadSpecificValue storage for the calling thread.
|
|
* @param index
|
|
* @param context
|
|
*/
|
|
template<typename T>
|
|
void Update(VersionedThreadSpecificType &versionedThreadSpecificValue, const size_t index, const T &context)
|
|
{
|
|
SharedType newSharedValue;
|
|
CreateSharedValueResult createSharedValueResult = Base::CREATE_SHARED_VALUE_NOOP_KEEP_STALE;
|
|
uint64_t initialSharedVersion = 0;
|
|
|
|
{
|
|
// Have to hold the mutex over the vector to have a peek. Not the end of the world; Update() is only
|
|
// called if we can't use the thread-specific copy and that is the important thing to keep lock-free.
|
|
ScopedMutexLocker scopedMutexLocker(this->m_pMutex);
|
|
|
|
if (index < this->m_sharedStorage.size())
|
|
initialSharedVersion = this->m_sharedStorage[index].m_version;
|
|
}
|
|
|
|
if (initialSharedVersion <= this->m_lastStaleVersion)
|
|
{
|
|
// Note we are not calling this with the mutex held. We don't know what the user's provided creation function
|
|
// may do, so can't hold a mutex. Multiple threads calling Get() at the same time may
|
|
// therefore invoke CreateSharedValue(); this is OK as the shared copy is then updated with the mutex held.
|
|
createSharedValueResult = this->GetDerived().CreateSharedValue(newSharedValue, context);
|
|
}
|
|
|
|
{
|
|
ScopedMutexLocker scopedMutexLocker(this->m_pMutex);
|
|
|
|
if (index >= this->m_sharedStorage.size())
|
|
this->m_sharedStorage.resize(index + 1);
|
|
|
|
VersionedSharedType &versionedSharedValue(this->m_sharedStorage[index]);
|
|
|
|
this->CommonUpdate(initialSharedVersion, createSharedValueResult, versionedSharedValue, newSharedValue,
|
|
versionedThreadSpecificValue);
|
|
}
|
|
}
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief The cache class that a user should derive from.
|
|
*
|
|
* @tparam DERIVED the class derived from LazyThreadSpecificCache.
|
|
* @tparam TYPES LazyThreadSpecificCacheTypes defining the shared and thread-specific types to be stored.
|
|
* @tparam THREAD_SPECIFIC_DATA the ThreadSpecificData type that will be storing the thread-specific data.
|
|
*/
|
|
template<typename DERIVED, typename TYPES, typename THREAD_SPECIFIC_DATA>
|
|
class LazyThreadSpecificCache : public LazyThreadSpecificCacheTagBase<typename TYPES::Tag, DERIVED, TYPES, THREAD_SPECIFIC_DATA>
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param pMutex mutex over the shared data.
|
|
* @param threadSpecificData reference to a ThreadSpecificData object handling thread-specific storage.
|
|
*/
|
|
LazyThreadSpecificCache(IMutex * const pMutex, THREAD_SPECIFIC_DATA &threadSpecificData) :
|
|
LazyThreadSpecificCacheTagBase<typename TYPES::Tag, DERIVED, TYPES, THREAD_SPECIFIC_DATA>(pMutex, threadSpecificData)
|
|
{
|
|
}
|
|
};
|
|
|
|
} // namespace Activ
|
|
|
|
#endif // (!defined ACTIV_MIDDLEWARE_MISC_LAZY_THREAD_SPECIFIC_CACHE_H)
|