dpp::cache< T > Class Template Reference

A cache object maintains a cache of dpp::managed objects. More...

#include <cache.h>

Public Member Functions
	cache ()
	Construct a new cache object. More...
	~cache ()
	Destroy the cache object. More...
void	store (T *object)
	Store an object in the cache. Passing a nullptr will have no effect. More...
void	remove (T *object)
	Remove an object from the cache. More...
T *	find (snowflake id)
	Find an object in the cache by id. More...
uint64_t	count ()
	Return a count of the number of items in the cache. More...
std::shared_mutex &	get_mutex ()
	Return the cache's locking mutex. More...
auto &	get_container ()
	Get the container unordered map. More...
void	rehash ()
	"Rehash" a cache by reallocating the map and copying all elements into the new one. More...
size_t	bytes ()
	Get "real" size in RAM of the cached objects. More...

Detailed Description

template<class T>
class dpp::cache< T >

A cache object maintains a cache of dpp::managed objects.

This is for example users, channels or guilds. You may instantiate your own caches, to contain any type derived from dpp::managed including your own types.

Note

This class is critical to the operation of the library and therefore designed with thread safety in mind.

Template Parameters

T	class type to store, which should be derived from dpp::managed.

Constructor & Destructor Documentation

cache()

template<class T >

dpp::cache< T >::cache ( )

inline

Construct a new cache object.

Caches must contain classes derived from dpp::managed.

~cache()

template<class T >

dpp::cache< T >::~cache ( )

inline

Destroy the cache object.

Note

This does not delete objects stored in the cache.

Member Function Documentation

bytes()

template<class T >

size_t dpp::cache< T >::bytes ( )

inline

Get "real" size in RAM of the cached objects.

This does not include metadata used to maintain the unordered map itself.

Returns

size_t size of cache in bytes

count()

template<class T >

uint64_t dpp::cache< T >::count ( )

inline

Return a count of the number of items in the cache.

This is used by the library e.g. to count guilds, users, and roles stored within caches. get

Returns

uint64_t count of items in the cache

find()

template<class T >

T * dpp::cache< T >::find ( snowflake  id )

inline

Find an object in the cache by id.

The cache is searched for the object. All dpp::managed objects have a snowflake id (this is the only field dpp::managed actually has).

Warning

Do not hang onto objects returned by cache::find() indefinitely. They may be deleted at a later date if cache::remove() is called. If persistence is required, take a copy of the object after checking its pointer is non-null.

Parameters

id	Object snowflake id to find

Returns

Found object or nullptr if the object with this id does not exist.

get_container()

template<class T >

auto & dpp::cache< T >::get_container ( )

inline

Get the container unordered map.

Warning

Be sure to use cache::get_mutex() correctly if you manipulate or iterate the map returned by this method! If you do not, this is not thread safe and will cause crashes!

See also

cache::get_mutex

Returns

A reference to the cache's container map

get_mutex()

template<class T >

std::shared_mutex & dpp::cache< T >::get_mutex ( )

inline

Return the cache's locking mutex.

Use this whenever you manipulate or iterate raw elements in the cache!

Note

If you are only reading from the cache's container, wrap this mutex in std::shared_lock, else wrap it in a std::unique_lock. Shared locks will allow for multiple readers whilst blocking writers, and unique locks will allow only one writer whilst blocking readers and writers.

Example:

dpp::cache<guild>* c = dpp::get_guild_cache();
std::unordered_map<snowflake, guild*>& gc = c->get_container();
std::shared_lock l(c->get_mutex()); // MUST LOCK HERE
for (auto g = gc.begin(); g != gc.end(); ++g) {
    dpp::guild* gp = (dpp::guild*)g->second;
    // Do something here with the guild* in 'gp'
}

Returns

The mutex used to protect the container

rehash()

template<class T >

void dpp::cache< T >::rehash ( )

inline

"Rehash" a cache by reallocating the map and copying all elements into the new one.

Over a long running timeframe, unordered maps can grow in size due to bucket allocation, this function frees that unused memory to keep the maps in control over time. If this is an issue which is apparent with your use of dpp::cache objects, you should periodically call this method.

Warning

May be time consuming! This function is O(n) in relation to the number of cached entries.

remove()

template<class T >

void dpp::cache< T >::remove ( T *  object )

inline

Remove an object from the cache.

Note

The cache class takes ownership of the pointer, and calling this method will cause deletion of the object within the next 60 seconds by means of a garbage collection queue. This queue aids in efficiency by freeing memory in bulk, and assists in thread safety by ensuring that all deletions can be locked and freed at the same time.

Parameters

object

object to remove. Passing a nullptr will have no effect.

store()

template<class T >

void dpp::cache< T >::store ( T *  object )

inline

Store an object in the cache. Passing a nullptr will have no effect.

The object must be derived from dpp::managed and should be allocated on the heap. Generally this is done via new. Once stored in the cache the lifetime of the stored object is managed by the cache class unless the cache is deleted (at which point responsibility for deleting the object returns to its allocator). Objects stored are removed when the cache::remove() method is called by placing them into a garbage collection queue for deletion within the next 60 seconds, which are then deleted in bulk for efficiency and to aid thread safety.

Note

Adding an object to the cache with an ID which already exists replaces that entry. The previously entered cache item is inserted into the garbage collection queue for deletion similarly to if cache::remove() was called first.

Parameters

object

object to store. Storing a pointer to the cache relinquishes ownership to the cache object.