Struct twilight_cache::InMemoryCache

pub struct InMemoryCache(_);

A thread-safe, in-memory-process cache of Discord data. It can be cloned and sent to other threads.

This is an implementation of Cache designed to be used by only the current process. If the cache needs to be used by other processes, consider using twilight-cache-redis or another cache.

Public Immutability

The defining characteristic of this cache is that returned types (such as a guild or user) do not use locking for access. Although the internals of the cache use asynchronous locking for mutability, the returned types themselves are immutable. If a user is retrieved from the cache, an Arc<User> is returned. If a reference to that user is held but the cache updates the user, the reference held by you will be outdated, but still exist.

The intended use is that data is held outside the cache for only as long as necessary, where the state of the value at that time doesn't need to be up-to-date.

Say you're deleting some of the guilds of a channel. You'll probably need the guild to do that, so you retrieve it from the cache. You can then use the guild to update all of the channels, because for most use cases you don't need the guild to be up-to-date in real time, you only need its state at that point in time. If you need the guild to always be up-to-date between operations, the intent is that you keep getting it from the cache.

Getting something from the cache is cheap and has low contention, so public immutability is preferred over using mutexes, read-write locks, or other smart atomic updating cells. Refer to the crate-level documentation for a list of known first-party and third-party cache implementations.

Caveats

• the "last message id" field of channels will not be kept up to date as
• messages come in.

Implementations

impl InMemoryCache

Implemented methods and types for the cache.

Note: This section may appear empty. Please read the implementation in the Cache trait implementation.

pub fn new() -> InMemoryCache

Creates a new, empty cache.

If you need to customize the cache, use the From<InMemoryConfig> implementation.

Examples

Creating a new InMemoryCache with a custom configuration, limiting the message cache to 50 messages per channel:

use twilight_cache_inmemory::{
    config::InMemoryConfig,
    InMemoryCache,
};

let config = InMemoryConfig::builder().message_cache_size(50);
let cache = InMemoryCache::from(config);

pub fn config(&self) -> InMemoryConfig

Returns a copy of the config cache.

pub async fn update<T>(&'_ self, value: &'_ T) -> Result<(), InMemoryCacheError> where
    T: UpdateCache<InMemoryCache, InMemoryCacheError>, 

pub async fn guild_channel(
    &'_ self,
    channel_id: ChannelId
) -> Result<Option<Arc<GuildChannel>>, InMemoryCacheError>

Gets a channel by ID.

This is an O(1) operation.

pub async fn current_user(
    &'_ self
) -> Result<Option<Arc<CurrentUser>>, InMemoryCacheError>

Gets the current user.

This is an O(1) operation.

pub async fn emoji(
    &'_ self,
    emoji_id: EmojiId
) -> Result<Option<Arc<CachedEmoji>>, InMemoryCacheError>

Gets an emoji by ID.

This is an O(1) operation.

pub async fn group(
    &'_ self,
    channel_id: ChannelId
) -> Result<Option<Arc<Group>>, InMemoryCacheError>

Gets a group by ID.

This is an O(1) operation.

pub async fn guild(
    &'_ self,
    guild_id: GuildId
) -> Result<Option<Arc<CachedGuild>>, InMemoryCacheError>

Gets a guild by ID.

This is an O(1) operation.

pub async fn member(
    &'_ self,
    guild_id: GuildId,
    user_id: UserId
) -> Result<Option<Arc<CachedMember>>, InMemoryCacheError>

Gets a member by guild ID and user ID.

This is an O(1) operation.

pub async fn message(
    &'_ self,
    channel_id: ChannelId,
    message_id: MessageId
) -> Result<Option<Arc<CachedMessage>>, InMemoryCacheError>

Gets a message by channel ID and message ID.

This is an O(log n) operation.

pub async fn presence(
    &'_ self,
    guild_id: Option<GuildId>,
    user_id: UserId
) -> Result<Option<Arc<CachedPresence>>, InMemoryCacheError>

Gets a presence by, optionally, guild ID, and user ID.

This is an O(1) operation.

pub async fn private_channel(
    &'_ self,
    channel_id: ChannelId
) -> Result<Option<Arc<PrivateChannel>>, InMemoryCacheError>

Gets a private channel by ID.

This is an O(1) operation.

pub async fn role(
    &'_ self,
    role_id: RoleId
) -> Result<Option<Arc<Role>>, InMemoryCacheError>

Gets a role by ID.

This is an O(1) operation.

pub async fn user(
    &'_ self,
    user_id: UserId
) -> Result<Option<Arc<User>>, InMemoryCacheError>

Gets a user by ID.

This is an O(1) operation.

pub async fn voice_state(
    &'_ self,
    user_id: UserId,
    guild_id: GuildId
) -> Result<Option<Arc<VoiceState>>, InMemoryCacheError>

Gets a voice state by user ID and Guild ID.

This is an O(1) operation.

pub async fn clear(&'_ self) -> Result<(), InMemoryCacheError>

Clears the entire state of the Cache. This is equal to creating a new empty Cache.

pub async fn cache_current_user(&'_ self, __arg1: CurrentUser)

pub async fn cache_guild_channels(
    &'_ self,
    guild_id: GuildId,
    guild_channels: impl IntoIterator<Item = GuildChannel>
) -> HashSet<ChannelId, RandomState>

pub async fn cache_guild_channel(
    &'_ self,
    guild_id: GuildId,
    __arg2: GuildChannel
) -> Arc<GuildChannel>

pub async fn cache_emoji(
    &'_ self,
    guild_id: GuildId,
    emoji: Emoji
) -> Arc<CachedEmoji>

pub async fn cache_emojis(
    &'_ self,
    guild_id: GuildId,
    emojis: impl IntoIterator<Item = Emoji>
) -> HashSet<EmojiId, RandomState>

pub async fn cache_group(&'_ self, group: Group) -> Arc<Group>

pub async fn cache_guild(&'_ self, guild: Guild)

pub async fn cache_member(
    &'_ self,
    guild_id: GuildId,
    member: Member
) -> Arc<CachedMember>

pub async fn cache_members(
    &'_ self,
    guild_id: GuildId,
    members: impl IntoIterator<Item = Member>
) -> HashSet<UserId, RandomState>

pub async fn cache_presences(
    &'_ self,
    guild_id: Option<GuildId>,
    presences: impl IntoIterator<Item = Presence>
) -> HashSet<UserId, RandomState>

pub async fn cache_presence(
    &'_ self,
    guild_id: Option<GuildId>,
    presence: Presence
) -> Arc<CachedPresence>

pub async fn cache_private_channel(
    &'_ self,
    private_channel: PrivateChannel
) -> Arc<PrivateChannel>

pub async fn cache_roles(
    &'_ self,
    guild_id: GuildId,
    roles: impl IntoIterator<Item = Role>
) -> HashSet<RoleId, RandomState>

pub async fn cache_role(&'_ self, guild_id: GuildId, role: Role) -> Arc<Role>

pub async fn cache_user(&'_ self, user: User) -> Arc<User>

pub async fn cache_voice_states(
    &'_ self,
    voice_states: impl IntoIterator<Item = VoiceState>
) -> HashSet<UserId, RandomState>

pub async fn delete_group(&'_ self, channel_id: ChannelId) -> Option<Arc<Group>>

pub async fn unavailable_guild(&'_ self, guild_id: GuildId)

pub async fn delete_guild_channel(
    &'_ self,
    channel_id: ChannelId
) -> Option<Arc<GuildChannel>>

pub async fn delete_role(&'_ self, role_id: RoleId) -> Option<Arc<Role>>

Trait Implementations

impl<'_> Cache for &'_ InMemoryCache

impl Cache for InMemoryCache

impl Clone for InMemoryCache

fn clone(&self) -> InMemoryCache

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for InMemoryCache

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for InMemoryCache

fn default() -> InMemoryCache

Returns the "default value" for a type.

impl<T> From<T> for InMemoryCache where
    T: Into<InMemoryConfig>, 

fn from(config: T) -> InMemoryCache

Performs the conversion.

impl UpdateCache<InMemoryCache, InMemoryCacheError> for TypingStart

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    __arg1: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    TypingStart: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for RoleDelete

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    RoleDelete: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for GuildDelete

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    GuildDelete: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for GuildUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    GuildUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for RoleUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    RoleUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for PresenceUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    PresenceUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for WebhooksUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    __arg1: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    WebhooksUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for BanRemove

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    __arg1: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    BanRemove: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for GuildEmojisUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    GuildEmojisUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MessageDelete

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MessageDelete: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MessageUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MessageUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for UserUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    UserUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MemberChunk

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MemberChunk: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for VoiceServerUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    VoiceServerUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for UnavailableGuild

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    UnavailableGuild: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ReactionAdd

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ReactionAdd: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for Ready

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Ready: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ChannelPinsUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ChannelPinsUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ReactionRemoveAll

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ReactionRemoveAll: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for Event

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    c: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Event: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ChannelDelete

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ChannelDelete: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MemberAdd

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MemberAdd: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for GuildIntegrationsUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    __arg1: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    GuildIntegrationsUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MessageDeleteBulk

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MessageDeleteBulk: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MemberRemove

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MemberRemove: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ReactionRemove

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ReactionRemove: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for RoleCreate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    RoleCreate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for GuildCreate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    GuildCreate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for BanAdd

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    __arg1: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    BanAdd: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ChannelCreate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ChannelCreate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MessageCreate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MessageCreate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for ChannelUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    ChannelUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for MemberUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    MemberUpdate: 'async_trait, 

impl UpdateCache<InMemoryCache, InMemoryCacheError> for VoiceStateUpdate

fn update<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cache: &'life1 InMemoryCache
) -> Pin<Box<dyn Future<Output = Result<(), InMemoryCacheError>> + 'async_trait + Send>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    VoiceStateUpdate: 'async_trait,