D++ (DPP)
C++ Discord API Bot Library
dpp::cache< T > Class Template Reference

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

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

Note
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
idObject 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:

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
objectobject 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
objectobject to store. Storing a pointer to the cache relinquishes ownership to the cache object.
dpp::guild
Represents a guild on Discord (AKA a server)
Definition: guild.h:1017
dpp::cache
A cache object maintains a cache of dpp::managed objects.
Definition: cache.h:70
dpp::get_guild_cache
DPP_EXPORT cache< class guild > * get_guild_cache()
dpp::cache::get_container
auto & get_container()
Get the container unordered map.
Definition: cache.h:236
dpp::cache::get_mutex
std::shared_mutex & get_mutex()
Return the cache's locking mutex.
Definition: cache.h:221
D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0