Struct twilight_cache_inmemory::InMemoryCache [−][src]
pub struct InMemoryCache(_);
Expand description
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
Implemented methods and types for the cache.
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();
Create a new builder to configure and construct an in-memory cache.
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);
This is supported on crate feature permission-calculator
only.
permission-calculator
only.Create an interface for retrieving the permissions of a member in a guild or channel.
ResourceType
s 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);
Update the cache with an event from the gateway.
Gets the current user.
This is an O(1) operation.
Gets an emoji by ID.
This is an O(1) operation. This requires the GUILD_EMOJIS
intent.
Gets a group by ID.
This is an O(1) operation.
Gets a guild by ID.
This is an O(1) operation. This requires the GUILDS
intent.
Gets a channel by ID.
This is an O(1) operation. This requires the GUILDS
intent.
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.
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.
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.
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.
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.
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.
Gets a member by guild ID and user ID.
This is an O(1) operation. This requires the GUILD_MEMBERS
intent.
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.
Gets a presence by, optionally, guild ID, and user ID.
This is an O(1) operation. This requires the GUILD_PRESENCES
intent.
Gets a private channel by ID.
This is an O(1) operation. This requires the DIRECT_MESSAGES
intent.
Gets a role by ID.
This is an O(1) operation. This requires the GUILDS
intent.
Gets a stage instance by ID.
This is an O(1) operation. This requires the GUILDS
intent.
Gets a user by ID.
This is an O(1) operation. This requires the GUILD_MEMBERS
intent.
Gets the voice states within a voice channel.
This requires both the GUILDS
and GUILD_VOICE_STATES
intents.
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.
Gets the highest role of a member.
This requires both the GUILDS
and GUILD_MEMBERS
intents.
Trait Implementations
Returns the “default value” for a type. Read more
Auto Trait Implementations
impl !RefUnwindSafe for InMemoryCache
impl Send for InMemoryCache
impl Sync for InMemoryCache
impl Unpin for InMemoryCache
impl !UnwindSafe for InMemoryCache
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more