Module serenity::ext::cache
[−]
[src]
A cache of events received over a Shard, where storing at least some
data from the event is possible.
This acts as a hot cache, to avoid making requests over the REST API through
the rest module where possible. All fields are public, and do not have
getters, to allow you more flexibility with the stored data. However, this
allows data to be "corrupted", and may or may not cause misfunctions
within the library. Mutate data at your own discretion.
A "globally available" instance of the Cache is available at
client::CACHE. This is the instance that is updated by the library,
meaning you should not need to maintain updating it yourself in any case.
Use by the Context
The Context will automatically attempt to pull from the cache for you.
For example, the Context::get_channel method will attempt to find the
channel in the cache. If it can not find it, it will perform a request
through the REST API, and then insert a clone of the channel - if found -
into the Cache, giving you the original.
This allows you to save a step, by only needing to perform the
Context::get_channel call and not need to first search through the cache
- and if not found - then perform an HTTP request through the Context or
rest module.
Additionally, note that some information received through events can not
be retrieved through the REST API. This is information such as Roles in
LiveGuilds.
Use by Models
Most models of Discord objects, such as the Message, PublicChannel,
or Emoji, have methods for interacting with that single instance. This
feature is only compiled if the methods feature is enabled. An example of
this is LiveGuild::edit, which performs a check to ensure that the
current user is the owner of the guild, prior to actually performing the
HTTP request. The cache is involved due to the function's use of unlocking
the cache and retrieving the Id of the current user, and comparing it to
the Id of the user that owns the guild. This is an inexpensive method of
being able to access data required by these sugary methods.
Do I need the Cache?
If you're asking this, the answer is likely "definitely yes" or "definitely no"; any in-between tends to be "yes". If you are low on RAM, and need to run on only a couple MB, then the answer is "definitely no". If you do not care about RAM and want your bot to be able to access data while needing to hit the REST API as little as possible, then the answer is "yes".
Special cases in the Cache
Some items in the cache, notably Calls and Groups, will "always be
empty". The exception to this rule, is for:
- Bots which used to be userbots prior to the conversion made available by Discord when the official Bot API was introduced;
- For groups and calls: 2a. Bots that have friends from before the conversion that have not been removed, as those users can still add the bots to groups; 2b. Bots that have the "Create Group" endpoint whitelisted specifically for them.
Structs
| Cache |
A cache of all events received over a |
Enums
| ChannelRef |
A reference to a private channel, guild's channel, or group. |