Struct twilight_cache_inmemory::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 a cache designed to be used by only the current process.

Events will only be processed if they are properly expressed with Intents; refer to function-level documentation for more details.

Cloning

The cache internally wraps its data within an Arc. This means that the cache can be cloned and passed around tasks and threads cheaply.

Design and Performance

The defining characteristic of this cache is that returned types (such as a guild or user) do not use locking for access. The internals of the cache use a concurrent map for mutability and the returned types are clones of the cached data. If a user is retrieved from the cache, then a clone of the user at that point in time is returned. If the cache updates the user, then the returned user held by you will be outdated.

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 point time doesn’t need to be up-to-date. If you need to ensure you always have the most up-to-date “version” of a cached resource, then you can re-retrieve it whenever you use it: retrieval operations are extremely cheap.

For example, 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 or maybe across the lifetime of an operation. If you need the guild to always be up-to-date between operations, then the intent is that you keep getting it from the cache.

Implementations

impl InMemoryCache

Implemented methods and types for the cache.

pub fn new() -> Self

Creates a new, empty cache.

Examples

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

use twilight_cache_inmemory::InMemoryCache;

let cache = InMemoryCache::builder().message_cache_size(50).build();

pub const fn builder() -> InMemoryCacheBuilder

Create a new builder to configure and construct an in-memory cache.

pub fn clear(&self)

Clear the state of the Cache.

This is equal to creating a new empty cache.

pub fn config(&self) -> Config

Returns a copy of the config cache.

pub const fn stats(&self) -> InMemoryCacheStats<'_>

Create an interface for retrieving statistics about the cache.

Examples

Print the number of guilds in a cache:

use twilight_cache_inmemory::InMemoryCache;

let cache = InMemoryCache::new();

// later on...
let guilds = cache.stats().guilds();
println!("guild count: {}", guilds);

pub const fn permissions(&self) -> InMemoryCachePermissions<'_>

This is supported on crate feature permission-calculator only.

Create an interface for retrieving the permissions of a member in a guild or channel.

ResourceTypes must be configured for the permission interface to properly work; refer to the permission module-level documentation for more information.

Examples

Calculate the permissions of a member in a guild channel:

use twilight_cache_inmemory::{InMemoryCache, ResourceType};
use twilight_model::id::{ChannelId, UserId};

let resource_types = ResourceType::CHANNEL
    | ResourceType::MEMBER
    | ResourceType::ROLE;

let cache = InMemoryCache::builder()
    .resource_types(resource_types)
    .build();

let channel_id = ChannelId(4);
let user_id = UserId(5);

let permissions = cache.permissions().in_channel(user_id, channel_id)?;
println!("member has these permissions: {:?}", permissions);

pub fn update(&self, value: &impl UpdateCache)

Update the cache with an event from the gateway.

pub fn current_user(&self) -> Option<CurrentUser>

Gets the current user.

This is an O(1) operation.

pub fn emoji(&self, emoji_id: EmojiId) -> Option<CachedEmoji>

Gets an emoji by ID.

This is an O(1) operation. This requires the GUILD_EMOJIS intent.

pub fn group(&self, channel_id: ChannelId) -> Option<Group>

Gets a group by ID.

This is an O(1) operation.

pub fn guild(&self, guild_id: GuildId) -> Option<CachedGuild>

Gets a guild by ID.

This is an O(1) operation. This requires the GUILDS intent.

pub fn guild_channel(&self, channel_id: ChannelId) -> Option<GuildChannel>

Gets a channel by ID.

This is an O(1) operation. This requires the GUILDS intent.

pub fn guild_channels(&self, guild_id: GuildId) -> Option<HashSet<ChannelId>>

Gets the set of channels in a guild.

This is a O(m) operation, where m is the amount of channels in the guild. This requires the GUILDS intent.

pub fn guild_emojis(&self, guild_id: GuildId) -> Option<HashSet<EmojiId>>

Gets the set of emojis in a guild.

This is a O(m) operation, where m is the amount of emojis in the guild. This requires both the GUILDS and GUILD_EMOJIS intents.

pub fn guild_integrations(
    &self,
    guild_id: GuildId
) -> Option<HashSet<IntegrationId>>

Gets the set of integrations in a guild.

This requires the GUILD_INTEGRATIONS intent. The ResourceType::INTEGRATION resource type must be enabled.

pub fn guild_members(&self, guild_id: GuildId) -> Option<HashSet<UserId>>

Gets the set of members in a guild.

This list may be incomplete if not all members have been cached.

This is a O(m) operation, where m is the amount of members in the guild. This requires the GUILD_MEMBERS intent.

pub fn guild_presences(&self, guild_id: GuildId) -> Option<HashSet<UserId>>

Gets the set of presences in a guild.

This list may be incomplete if not all members have been cached.

This is a O(m) operation, where m is the amount of members in the guild. This requires the GUILD_PRESENCES intent.

pub fn guild_roles(&self, guild_id: GuildId) -> Option<HashSet<RoleId>>

Gets the set of roles in a guild.

This is a O(m) operation, where m is the amount of roles in the guild. This requires the GUILDS intent.

pub fn guild_stage_instances(
    &self,
    guild_id: GuildId
) -> Option<HashSet<StageId>>

Gets the set of stage instances in a guild.

This is a O(m) operation, where m is the amount of stage instances in the guild. This requires the GUILDS intent.

pub fn integration(
    &self,
    guild_id: GuildId,
    integration_id: IntegrationId
) -> Option<GuildIntegration>

Gets an integration by guild ID and integration ID.

This is an O(1) operation. This requires the GUILD_INTEGRATIONS intent. The ResourceType::INTEGRATION resource type must be enabled.

pub fn member(&self, guild_id: GuildId, user_id: UserId) -> Option<CachedMember>

Gets a member by guild ID and user ID.

This is an O(1) operation. This requires the GUILD_MEMBERS intent.

pub fn message(
    &self,
    channel_id: ChannelId,
    message_id: MessageId
) -> Option<CachedMessage>

Gets a message by channel ID and message ID.

This is an O(n) operation. This requires one or both of the GUILD_MESSAGES or DIRECT_MESSAGES intents.

pub fn presence(
    &self,
    guild_id: GuildId,
    user_id: UserId
) -> Option<CachedPresence>

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

This is an O(1) operation. This requires the GUILD_PRESENCES intent.

pub fn private_channel(&self, channel_id: ChannelId) -> Option<PrivateChannel>

Gets a private channel by ID.

This is an O(1) operation. This requires the DIRECT_MESSAGES intent.

pub fn role(&self, role_id: RoleId) -> Option<Role>

Gets a role by ID.

This is an O(1) operation. This requires the GUILDS intent.

pub fn stage_instance(&self, stage_id: StageId) -> Option<StageInstance>

Gets a stage instance by ID.

This is an O(1) operation. This requires the GUILDS intent.

pub fn user(&self, user_id: UserId) -> Option<User>

Gets a user by ID.

This is an O(1) operation. This requires the GUILD_MEMBERS intent.

pub fn voice_channel_states(
    &self,
    channel_id: ChannelId
) -> Option<Vec<VoiceState>>

Gets the voice states within a voice channel.

This requires both the GUILDS and GUILD_VOICE_STATES intents.

pub fn voice_state(
    &self,
    user_id: UserId,
    guild_id: GuildId
) -> Option<VoiceState>

Gets a voice state by user ID and Guild ID.

This is an O(1) operation. This requires both the GUILDS and GUILD_VOICE_STATES intents.

pub fn member_highest_role(
    &self,
    guild_id: GuildId,
    user_id: UserId
) -> Option<RoleId>

Gets the highest role of a member.

This requires both the GUILDS and GUILD_MEMBERS intents.

Trait Implementations

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

Formats the value using the given formatter.

impl Default for InMemoryCache

fn default() -> InMemoryCache

Returns the “default value” for a type.