Discord::Cache
Inherits Reference / Object
A cache is a utility class that stores various kinds of Discord objects,
like Users, Roles etc. Its purpose is to reduce both the load on
Discord's servers and reduce the latency caused by having to do an API call.
It is recommended to use caching for bots that interact heavily with
Discord-provided data, like for example administration bots, as opposed to
bots that only interact by sending and receiving messages. For that latter
kind, caching is usually even counter-productive as it only unnecessarily
increases memory usage.
Caching can either be used standalone, in a purely REST-based way:
client = Discord::Client.new(token: "Bot token", client_id: 123_u64)
cache = Discord::Cache.new(client)
puts cache.resolve_user(66237334693085184) # will perform API call
puts cache.resolve_user(66237334693085184) # will not perform an API call, as the data is now cachedIt can also be integrated more deeply into a Client (specifically one that
uses a gateway connection) to reduce cache misses even more by automatically
caching data received over the gateway:
client = Discord::Client.new(token: "Bot token", client_id: 123_u64)
cache = Discord::Cache.new(client)
client.cache = cache # Integrate the cache into the clientNote that if a cache is not used this way, its data will slowly go out of sync with Discord, and unless it is used in an environment with few changes likely to occur, a client without a gateway connection should probably refrain from caching at all.
Constructors
Creates a new cache with a client that requests (in case of cache misses) should be done on.
Instance methods
Marks a channel, identified by the channel_id, as belonging to a particular guild, identified by the guild_id.
Marks a role, identified by the role_id, as belonging to a particular guild, identified by the guild_id.
Marks a Stage instance, identified by the instance_id, as belonging to a particular guild, identified by the guild_id.
Adds a specific member to the cache, given the guild_id it is on.
Adds a particular DM channel to the cache, given the channel_id and the recipient_id.
Adds multiple members at once to the cache, given the guild_id they all share. This method exists to slightly reduce the overhead of processing chunks; outside of that it is likely not of much use.
A map of cached channels, i. e. all channels on all servers the bot is on, as well as all DM channels.
Deletes a DM channel with a particular user given the recipient_id.
Deletes a member from the cache given its user_id and the guild_id it is on.
Deletes a stage instance from the cache given its ID.
Deletes voice state for user in guild from cache.
Mapping of users to the respective DM channels the bot has open with them, represented as {user ID => channel ID}.
Returns all channels of a guild, identified by its guild_id.
Mapping of guilds to the channels on them, represented as {guild ID => [channel IDs]}.
Returns all roles of a guild, identified by its guild_id.
Returns all Stage instances of a guild, identified by its guild_id.
Mapping of guilds to the Stage instances on them, represented as {guild ID => [stage instance IDs]}.
A map of guilds (servers) the bot is on. Doesn't ignore guilds temporarily deleted due to an outage; so if an outage is going on right now the affected guilds would be missing here too.
A double map of members on servers, represented as {guild ID => {user ID
=> member}}. Will only contain previously and currently online members as
well as all members that have been chunked (see
Client#request_guild_members).
Marks a channel as not belonging to a particular guild anymore.
Marks a role as not belonging to a particular guild anymore.
Marks a Stage instance as not belonging to a particular guild anymore.
Resolves a channel by its ID. If the requested object is not cached, it will do an API call.
Resolves the current user's profile. Requires no parameters since the endpoint has none either. If there is a gateway connection this should always be cached.
Resolves the ID of a DM channel with a particular user by the recipient's recipient_id. If there is no such channel cached, one will be created.
Resolves a guild by its ID. If the requested object is not cached, it will do an API call.
Resolves a member by the guild_id of the guild the member is on, and the user_id of the member itself. An API request will be performed if the object is not cached.
Resolves a role by its ID. No API request will be performed if the role is not cached, because there is no endpoint for individual roles; however all roles should be cached at all times so it won't be a problem.
Resolves a Stage instance by its ID. An API request will be performed if the object is not cached.
Resolves a user by its ID. If the requested object is not cached, it will do an API call.
Resolves a voice state by guild ID and user ID. No API request will be performed if voice state is not cached, because there is no endpoint for it. If there is a gateway connection this should always be cached.
A map of all roles on servers the bot is on. Does not discriminate by guild, as role IDs are unique even across guilds.
A map of cached stage instances, i. e. all stage instances on all servers the bot is on.
A map of cached users. These aren't necessarily all the users in servers
the bot has access to, but rather all the users that have been seen by
the bot in the past (and haven't been deleted by means of delete_user).
Mapping of users in guild to voice states, represented as {guild ID => {user ID => voice state}}