Skip to content

Commit

Permalink
Make Guild::shard_id follow additive features (#2813)
Browse files Browse the repository at this point in the history
This PR:
- Removes the `cache` feature locked function that called shard_count
for the user, since that is useless and breaks the "all features should
be additive" guidance
- Removes the useless example that just showed how to call a function
- Removed duplicate documentation on Guild, PartialGuild, and
InviteGuild just to direct to the canonical documentation where the
function is implemented.
  • Loading branch information
GnomedDev committed Mar 25, 2024
1 parent 63cc019 commit aa90cc6
Show file tree
Hide file tree
Showing 6 changed files with 22 additions and 135 deletions.
2 changes: 1 addition & 1 deletion src/cache/event.rs
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ impl CacheUpdate for ReadyEvent {
for guild_entry in cache.guilds.iter() {
let guild = guild_entry.key();
// Only handle data for our shard.
if crate::utils::shard_id(*guild, shard_data.total.get()) == shard_data.id.0
if crate::utils::shard_id(*guild, shard_data.total) == shard_data.id.0
&& !ready_guilds_hashset.contains(guild)
{
guilds_to_remove.push(*guild);
Expand Down
35 changes: 4 additions & 31 deletions src/model/guild/guild_id.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1210,40 +1210,13 @@ impl GuildId {

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
/// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
/// This is just a shortcut for [`utils::shard_id`], the shard count should
/// be fetched using [`Cache::shard_count`] if possible.
///
/// [`utils::shard_id`]: crate::utils::shard_id
#[cfg(all(feature = "cache", feature = "utils"))]
#[must_use]
pub fn shard_id(self, cache: &Cache) -> u16 {
crate::utils::shard_id(self, cache.shard_count().get())
}

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// When the cache is not enabled, the total number of shards being used will need to be
/// passed.
///
/// # Examples
///
/// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
///
/// ```rust
/// use serenity::model::id::GuildId;
/// use serenity::utils;
///
/// let guild_id = GuildId::new(81384788765712384);
///
/// assert_eq!(guild_id.shard_id(17), 7);
/// ```
#[cfg(all(feature = "utils", not(feature = "cache")))]
#[must_use]
pub fn shard_id(self, shard_count: u16) -> u16 {
#[cfg(feature = "utils")]
pub fn shard_id(self, shard_count: std::num::NonZeroU16) -> u16 {
crate::utils::shard_id(self, shard_count)
}

Expand Down
36 changes: 4 additions & 32 deletions src/model/guild/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2033,39 +2033,11 @@ impl Guild {

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
/// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
///
/// [`utils::shard_id`]: crate::utils::shard_id
#[cfg(all(feature = "cache", feature = "utils"))]
pub fn shard_id(&self, cache: &Cache) -> u16 {
self.id.shard_id(cache)
}

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// When the cache is not enabled, the total number of shards being used will need to be
/// passed.
///
/// # Examples
///
/// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
///
/// ```rust,ignore
/// use serenity::utils;
///
/// // assumes a `guild` has already been bound
///
/// assert_eq!(guild.shard_id(17), 7);
/// ```
#[cfg(all(feature = "utils", not(feature = "cache")))]
/// See the documentation for [`GuildId::shard_id`].
#[must_use]
pub fn shard_id(&self, shard_count: u16) -> u16 {
self.id.shard_id(shard_count)
#[cfg(feature = "utils")]
pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
self.id.shard_id(shard_total)
}

/// Returns the formatted URL of the guild's splash image, if one exists.
Expand Down
37 changes: 4 additions & 33 deletions src/model/guild/partial_guild.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1205,40 +1205,11 @@ impl PartialGuild {

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
/// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
///
/// [`utils::shard_id`]: crate::utils::shard_id
#[cfg(all(feature = "cache", feature = "utils"))]
#[must_use]
pub fn shard_id(&self, cache: &Cache) -> u16 {
self.id.shard_id(cache)
}

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// When the cache is not enabled, the total number of shards being used will need to be
/// passed.
///
/// # Examples
///
/// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
///
/// ```rust,ignore
/// use serenity::utils;
///
/// // assumes a `guild` has already been bound
///
/// assert_eq!(guild.shard_id(17), 7);
/// ```
#[cfg(all(feature = "utils", not(feature = "cache")))]
/// See the documentation for [`GuildId::shard_id`].
#[must_use]
pub fn shard_id(&self, shard_count: u16) -> u16 {
self.id.shard_id(shard_count)
#[cfg(feature = "utils")]
pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
self.id.shard_id(shard_total)
}

/// Returns the formatted URL of the guild's splash image, if one exists.
Expand Down
39 changes: 4 additions & 35 deletions src/model/invite.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@ use nonmax::NonMaxU64;
use super::prelude::*;
#[cfg(feature = "model")]
use crate::builder::CreateInvite;
#[cfg(all(feature = "cache", feature = "model"))]
use crate::cache::Cache;
#[cfg(feature = "model")]
use crate::http::{CacheHttp, Http};
use crate::internal::prelude::*;
Expand Down Expand Up @@ -228,40 +226,11 @@ pub struct InviteGuild {
impl InviteGuild {
/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// **Note**: When the cache is enabled, this function unlocks the cache to retrieve the total
/// number of shards in use. If you already have the total, consider using [`utils::shard_id`].
///
/// [`utils::shard_id`]: crate::utils::shard_id
#[cfg(all(feature = "cache", feature = "utils"))]
#[must_use]
pub fn shard_id(&self, cache: &Cache) -> u16 {
self.id.shard_id(cache)
}

/// Returns the Id of the shard associated with the guild.
///
/// When the cache is enabled this will automatically retrieve the total number of shards.
///
/// When the cache is not enabled, the total number of shards being used will need to be
/// passed.
///
/// # Examples
///
/// Retrieve the Id of the shard for a guild with Id `81384788765712384`, using 17 shards:
///
/// ```rust,ignore
/// use serenity::utils;
///
/// // assumes a `guild` has already been bound
///
/// assert_eq!(guild.shard_id(17), 7);
/// ```
#[cfg(all(feature = "utils", not(feature = "cache")))]
/// See the documentation for [`GuildId::shard_id`].
#[must_use]
pub fn shard_id(&self, shard_count: u16) -> u16 {
self.id.shard_id(shard_count)
#[cfg(feature = "utils")]
pub fn shard_id(&self, shard_total: std::num::NonZeroU16) -> u16 {
self.id.shard_id(shard_total)
}
}

Expand Down
8 changes: 5 additions & 3 deletions src/utils/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -478,11 +478,13 @@ pub(crate) fn user_perms(
/// use serenity::model::id::GuildId;
/// use serenity::utils;
///
/// assert_eq!(utils::shard_id(GuildId::new(81384788765712384), 17), 7);
/// let guild_id = GuildId::new(81384788765712384);
/// let shard_total = std::num::NonZeroU16::new(17).unwrap();
///
/// assert_eq!(utils::shard_id(guild_id, shard_total), 7);
/// ```
#[must_use]
pub fn shard_id(guild_id: GuildId, shard_count: u16) -> u16 {
let shard_count = check_shard_total(shard_count);
pub fn shard_id(guild_id: GuildId, shard_count: NonZeroU16) -> u16 {
((guild_id.get() >> 22) % u64::from(shard_count.get())) as u16
}

Expand Down

0 comments on commit aa90cc6

Please sign in to comment.