| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
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.
| ~cache ()
| Destroy the cache object.
size_t | bytes ()
| Get "real" size in RAM of the cached objects.
uint64_t | count ()
| Return a count of the number of items in the cache.
T * | find (snowflake id)
| Find an object in the cache by id.
auto & | get_container ()
| Get the container unordered map.
std::shared_mutex & | get_mutex ()
| Return the cache's locking mutex.
void | rehash ()
| "Rehash" a cache by reallocating the map and copying all elements into the new one.
void | remove (T *object)
| Remove an object from the cache.
void | store (T *object)
| Store an object in the cache. Passing a nullptr will have no effect.

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

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

  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'
}
dpp::cache
A cache object maintains a cache of dpp::managed objects.
Definition cache.h:50
dpp::cache::get_mutex
std::shared_mutex & get_mutex()
Return the cache's locking mutex.
Definition cache.h:201
dpp::cache::get_container
auto & get_container()
Get the container unordered map.
Definition cache.h:216
dpp::guild
Represents a guild on Discord (AKA a server).
Definition guild.h:999
dpp::get_guild_cache
DPP_EXPORT cache< class guild > * get_guild_cache()

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.

D++ Library version 9.0.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0