dpp::cache
cache.h
class T
std::unordered_map< snowflake, T * > * std::unordered_map<snowflake, T*>* dpp::cache< T >::cache_map cache_map dpp::cache::cache_map

Container of pointers to cached items.

std::shared_mutex std::shared_mutex dpp::cache< T >::cache_mutex cache_mutex dpp::cache::cache_mutex

Mutex to protect the cache.

This is a shared mutex so reading is cheap.

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

Construct a new cache object.

Caches must contain classes derived from dpp::managed.

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

Destroy the cache object.

This does not delete objects stored in the cache.

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

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

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

size_t size of cache in bytes

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

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

uint64_t count of items in the cache

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

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

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.

id

Object snowflake id to find

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

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

Get the container unordered map.

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!

cache::get_mutex

A reference to the cache's container map

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

Return the cache's locking mutex.

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

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_lockl(c->get_mutex());//MUSTLOCKHERE
    for(autog=gc.begin();g!=gc.end();++g){
    dpp::guild*gp=(dpp::guild*)g->second;
    //Dosomethingherewiththeguild*in'gp'
    }

The mutex used to protect the container

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

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

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

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

Remove an object from the cache.

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.

object

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

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

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.

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.

object

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

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.

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

T

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

- dpp::cache
  bytes
- dpp::cache
  cache
- dpp::cache
  cache_map
- dpp::cache
  cache_mutex
- dpp::cache
  count
- dpp::cache
  find
- dpp::cache
  get_container
- dpp::cache
  get_mutex
- dpp::cache
  rehash
- dpp::cache
  remove
- dpp::cache
  store
- dpp::cache
  ~cache