class Discord::Cache

Overview

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 cached

It 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 client

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

Defined in:

discordcr/cache.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(client : Client) #

Creates a new cache with a client that requests (in case of cache misses) should be done on.


[View source]

Instance Method Detail

def add_guild_channel(guild_id : UInt64 | Snowflake, channel_id : UInt64 | Snowflake) #

Marks a channel, identified by the channel_id, as belonging to a particular guild, identified by the guild_id.


[View source]
def add_guild_role(guild_id : UInt64 | Snowflake, role_id : UInt64 | Snowflake) #

Marks a role, identified by the role_id, as belonging to a particular guild, identified by the guild_id.


[View source]
def add_guild_stage_instance(guild_id : UInt64 | Snowflake, channel_id : UInt64 | Snowflake) #

Marks a Stage instance, identified by the channel_id it is on, as belonging to a particular guild, identified by the guild_id.


[View source]
def cache(member : GuildMember, guild_id : UInt64 | Snowflake) #

Adds a specific member to the cache, given the guild_id it is on.


[View source]
def cache(user : User) #

Adds a specific user to the cache.


[View source]
def cache(channel : Channel) #

Adds a specific channel to the cache.


[View source]
def cache(guild : Guild) #

Adds a specific guild to the cache.


[View source]
def cache(role : Role) #

Adds a specific role to the cache.


[View source]
def cache(stage_instance : StageInstance) #

Adds a specific Stage instance to the cache.


[View source]
def cache(voice_state : VoiceState) #

Adds a specific voice state to the cache.


[View source]
def cache_current_user(current_user : User) #

Caches the current user.


[View source]
def cache_dm_channel(channel_id : UInt64 | Snowflake, recipient_id : UInt64 | Snowflake) #

Adds a particular DM channel to the cache, given the channel_id and the recipient_id.


[View source]
def cache_multiple_members(members : Array(GuildMember), guild_id : UInt64 | Snowflake) #

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.


[View source]
def channels : Hash(UInt64, Discord::Channel) #

A map of cached channels, i. e. all channels on all servers the bot is on, as well as all DM channels.


[View source]
def delete_channel(id : UInt64 | Snowflake) #

Deletes a channel from the cache given its ID.


[View source]
def delete_current_user #

Deletes the current user from the cache, if that will ever be necessary.


[View source]
def delete_dm_channel(recipient_id : UInt64 | Snowflake) #

Deletes a DM channel with a particular user given the recipient_id.


[View source]
def delete_guild(id : UInt64 | Snowflake) #

Deletes a guild from the cache given its ID.


[View source]
def delete_member(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Deletes a member from the cache given its user_id and the guild_id it is on.


[View source]
def delete_role(id : UInt64 | Snowflake) #

Deletes a role from the cache given its ID.


[View source]
def delete_stage_instance(channel_id : UInt64 | Snowflake) #

Deletes a stage instance from the cache given the channel_id it belongs to.


[View source]
def delete_user(id : UInt64 | Snowflake) #

Deletes a user from the cache given its ID.


[View source]
def delete_voice_state(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) #

Deletes voice state for user in guild from cache.


[View source]
def dm_channels : Hash(UInt64, UInt64) #

Mapping of users to the respective DM channels the bot has open with them, represented as {user ID => channel ID}.


[View source]
def guild_channels(guild_id : UInt64 | Snowflake) : Array(UInt64) #

Returns all channels of a guild, identified by its guild_id.


[View source]
def guild_channels : Hash(UInt64, Array(UInt64)) #

Mapping of guilds to the channels on them, represented as {guild ID => [channel IDs]}.


[View source]
def guild_roles(guild_id : UInt64 | Snowflake) : Array(UInt64) #

Returns all roles of a guild, identified by its guild_id.


[View source]
def guild_roles : Hash(UInt64, Array(UInt64)) #

Mapping of guilds to the roles on them, represented as {guild ID => [role IDs]}.


[View source]
def guild_stage_instances(guild_id : UInt64 | Snowflake) : Array(UInt64) #

Returns all Stage instances of a guild, identified by its guild_id.


[View source]
def guild_stage_instances : Hash(UInt64, Array(UInt64)) #

Mapping of guilds to the channels with Stage instances on them, represented as {guild ID => [channel IDs]}.


[View source]
def guilds : Hash(UInt64, Discord::Guild) #

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.


[View source]
def members : Hash(UInt64, Hash(UInt64, Discord::GuildMember)) #

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


[View source]
def remove_guild_channel(guild_id : UInt64 | Snowflake, channel_id : UInt64 | Snowflake) #

Marks a channel as not belonging to a particular guild anymore.


[View source]
def remove_guild_role(guild_id : UInt64 | Snowflake, role_id : UInt64 | Snowflake) #

Marks a role as not belonging to a particular guild anymore.


[View source]
def remove_guild_stage_instance(guild_id : UInt64 | Snowflake, channel_id : UInt64 | Snowflake) #

Marks a Stage instance, identified by the channel_id it is on, as not belonging to a particular guild, identified by the guild_id, anymore.


[View source]
def resolve_channel(id : UInt64 | Snowflake) : Channel #

Resolves a channel by its ID. If the requested object is not cached, it will do an API call.


[View source]
def resolve_current_user : User #

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.


[View source]
def resolve_dm_channel(recipient_id : UInt64 | Snowflake) : UInt64 #

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.


[View source]
def resolve_guild(id : UInt64 | Snowflake) : Guild #

Resolves a guild by its ID. If the requested object is not cached, it will do an API call.


[View source]
def resolve_member(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) : GuildMember #

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.


[View source]
def resolve_role(id : UInt64 | Snowflake) : Role #

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.


[View source]
def resolve_stage_instance(channel_id : UInt64 | Snowflake) : StageInstance #

Resolves a Stage instance by the channel ID it is on. An API request will be performed if the object is not cached.


[View source]
def resolve_user(id : UInt64 | Snowflake) : User #

Resolves a user by its ID. If the requested object is not cached, it will do an API call.


[View source]
def resolve_voice_state(guild_id : UInt64 | Snowflake, user_id : UInt64 | Snowflake) : VoiceState #

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.


[View source]
def roles : Hash(UInt64, Discord::Role) #

A map of all roles on servers the bot is on. Does not discriminate by guild, as role IDs are unique even across guilds.


[View source]
def stage_instances : Hash(UInt64, Discord::StageInstance) #

A map of cached stage instances, i. e. all stage instances on all servers the bot is on, represented as {channel ID => Stage instance}.


[View source]
def users : Hash(UInt64, Discord::User) #

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


[View source]
def voice_states : Hash(UInt64, Hash(UInt64, Discord::VoiceState)) #

Mapping of users in guild to voice states, represented as {guild ID => {user ID => voice state}}


[View source]