carb::settings::ThreadSafeLocalCache

Defined in carb/settings/SettingsUtils.h

template<typename SettingType>
class ThreadSafeLocalCache

A utility for caching a setting and automatically subscribing to changes of the value, as opposed to constantly polling.

Thread Safety

Despite the name, this class is not thread-safe except that another thread may change the setting value and *this will have the cached value updated in a thread-safe manner. Unless otherwise specified, assume that calls to all functions must be serialized externally.

Template Parameters

SettingType – The type of the setting. Must be a supported setting value type or compilation errors will result: bool, int32_t, int64_t, float, double, const char*.

Public Functions

inline ThreadSafeLocalCache(SettingType initState = SettingType{})

Constructor.

Note

The value is not read from ISettings and tracking does not start until startTracking() is called. Attempting to read the value before calling startTracking() will result in an assert.

Parameters

initState – The initial value to cache.

inline ~ThreadSafeLocalCache()

Destructor.

Calls stopTracking().

inline void startTracking(const char *settingPath)

Reads the value from the settings database and subscribes to changes for the value.

This function reads the setting value at the given settingPath and caches it. Then ISettings::subscribeToNodeChangeEvents is called so that *this can be notified of changes to the value.

Note

Assertions will occur if settingPath is nullptr or tracking is already started without calling stopTracking() first.

Parameters

settingPath – The path of the setting to read. Must not be nullptr.

inline void stopTracking()

Halts tracking changes on the setting key provided with startTracking().

It is safe to call this function even if tracking has already been stopped, or never started. Do not call get() after calling this function without calling startTracking() prior, otherwise an assertion will occur.

inline SettingType get() const

Retrieves the cached value.

Thread Safety

This function is safe to call from multiple threads, though if the setting value is changed by other threads, multiple threads calling this function may receive different results.

Warning

get() may only be called while a subscription is active. A subscription is only active once startTracking() has been called (including on a newly constructed object), and only until stopTracking() is called (at which point startTracking() may be called to resume). Calling this function when a subscription is not active will result in an assertion and potentially reading a stale value.

Returns

The cached value of the setting key provided in startTracking().

inline operator SettingType() const

Syntactic sugar for get().

inline void set(SettingType value)

Sets the value in the setting database.

Note

Do not call this function after stopTracking() has been called and/or before startTracking() has been called, otherwise an assertion will occur and the setting database may be corrupted.

Parameters

value – The new value to set for the setting key given to startTracking().

inline bool isValueDirty() const

Checks to see if the cached value has been updated.

The dirty flag must be manually reset by calling clearValueDirty(). The dirty flag is set any time the cached value is updated through the subscription. This also includes calls to set(SettingType).

Returns

true if the dirty flag is set; false otherwise.

inline void clearValueDirty()

Resets the dirty flag.

After this function returns (and assuming that the subscription has not updated the cached value on a different thread), isValueDirty() will return false.

inline const char *getSettingsPath() const

Retrieves the setting key previously given to startTracking().

Returns

The setting key previously given to startTracking().

inline dictionary::IDictionary *getDictionaryInterface() const

Retrieves the cached dictionary::IDictionary pointer.

Returns

The cached dictionary::IDictionary pointer.