1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
use super::Cache;
/// Trait used for updating the cache with a type.
///
/// This may be implemented on a type and used to update the cache via
/// [`Cache::update`].
///
/// # Examples
///
/// Creating a custom struct implementation to update the cache with:
///
/// ```rust
/// use serenity::{
/// cache::{Cache, CacheUpdate},
/// model::{
/// id::UserId,
/// user::User,
/// },
/// prelude::RwLock,
/// };
/// use std::{
/// collections::hash_map::Entry,
/// sync::Arc,
/// };
///
/// // For example, an update to the user's record in the database was
/// // published to a pubsub channel.
/// struct DatabaseUserUpdate {
/// user_avatar: Option<String>,
/// user_discriminator: u16,
/// user_id: UserId,
/// user_is_bot: bool,
/// user_name: String,
/// }
///
/// impl CacheUpdate for DatabaseUserUpdate {
/// // A copy of the old user's data, if it existed in the cache.
/// type Output = User;
///
/// fn update(&mut self, cache: &mut Cache) -> Option<Self::Output> {
/// // If an entry for the user already exists, update its fields.
/// match cache.users.entry(self.user_id) {
/// Entry::Occupied(entry) => {
/// let user = entry.get();
/// let mut writer = user.write();
/// let old = writer.clone();
///
/// writer.bot = self.user_is_bot;
/// writer.discriminator = self.user_discriminator;
/// writer.id = self.user_id;
///
/// if writer.avatar != self.user_avatar {
/// writer.avatar = self.user_avatar.clone();
/// }
///
/// if writer.name != self.user_name {
/// writer.name = self.user_name.clone();
/// }
///
/// // Return the old copy for the user's sake.
/// Some(old)
/// },
/// Entry::Vacant(entry) => {
/// entry.insert(Arc::new(RwLock::new(User {
/// id: self.user_id,
/// avatar: self.user_avatar.clone(),
/// bot: self.user_is_bot,
/// discriminator: self.user_discriminator,
/// name: self.user_name.clone(),
/// })));
///
/// // There was no old copy, so return None.
/// None
/// },
/// }
/// }
/// }
///
/// // Create an instance of the cache.
/// let mut cache = Cache::new();
///
/// // This is a sample pubsub message that you might receive from your
/// // database.
/// let mut update_message = DatabaseUserUpdate {
/// user_avatar: None,
/// user_discriminator: 6082,
/// user_id: UserId(379740138303127564),
/// user_is_bot: true,
/// user_name: "TofuBot".to_owned(),
/// };
///
/// // Update the cache with the message.
/// cache.update(&mut update_message);
/// ```
///
/// [`Cache::update`]: struct.Cache.html#method.update
pub trait CacheUpdate {
/// The return type of an update.
///
/// If there is nothing to return, specify this type as an unit (`()`).
type Output;
/// Updates the cache with the implementation.
fn update(&mut self, &mut Cache) -> Option<Self::Output>;
}
|