Struct ShardId

pub struct ShardId { /* private fields */ }

Shard identifier to calculate if it receivies a given event.

A shard ID consist of two fields: number and total. These values do not need to be unique, and are used by Discord for calculating which events to send to which shard. Shards should in general share the same total value and have an unique number value, but users may deviate from this when resharding/migrating to a new set of shards.

Advanced use

Incoming events are split by their originating guild and are received by the shard with the id calculated from the following formula:

number = (guild_id >> 22) % total.

total is in other words unrelated to the total number of shards and is only used to specify the share of events a shard will receive. The formula is independently calculated for all shards, which means that events may be duplicated or lost if it’s determined that an event should be sent to multiple or no shard.

It may be helpful to visualize the logic in code:

for shard in shards {
    if shard.id().number() == (guild_id >> 22) % shard.id().total() {
        unimplemented!("send event to shard");
    }
}

See Discord Docs/Sharding.

Implementations

impl ShardId

pub const ONE: ShardId

ID of a bot that has only one shard.

Should only be used by small bots in under one or two thousand guilds.

pub const fn new(number: u32, total: u32) -> ShardId

Create a new shard identifier.

The shard number is 0-indexed while the total number of shards is 1-indexed. A shard number of 7 with a total of 8 is therefore valid, whilst a shard number of 8 out of 8 total shards is invalid.

Examples

Create a new shard with a shard number of 13 out of a total of 24 shards:

use twilight_model::gateway::ShardId;

let id = ShardId::new(13, 24);

Panics

Panics if the shard number is greater than or equal to the total number of shards.

pub const fn new_checked(number: u32, total: u32) -> Option<ShardId>

Create a new shard identifier if the shard indexes are valid.

pub const fn number(self) -> u32

Identifying number of the shard, 0-indexed.

pub const fn total(self) -> u32

Total number of shards, 1-indexed.

Trait Implementations

impl Clone for ShardId

fn clone(&self) -> ShardId

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ShardId

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ShardId

fn deserialize<__D>( __deserializer: __D, ) -> Result<ShardId, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ShardId

Display the shard ID.

Formats as [{number}, {total}].

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

Formats the value using the given formatter.

impl Hash for ShardId

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for ShardId

fn eq(&self, other: &ShardId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ShardId

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<[u32; 2]> for ShardId

type Error = ShardIdParseError

The type returned in the event of a conversion error.

fn try_from( _: [u32; 2], ) -> Result<ShardId, <ShardId as TryFrom<[u32; 2]>>::Error>

Performs the conversion.

impl Copy for ShardId

impl Eq for ShardId

impl StructuralPartialEq for ShardId