pub struct Shard {
pub client: WsStream,
pub started: Instant,
pub token: String,
pub intents: GatewayIntents,
/* private fields */
}
gateway
only.Expand description
A Shard is a higher-level handler for a websocket connection to Discord’s gateway. The shard allows for sending and receiving messages over the websocket, such as setting the active activity, reconnecting, syncing guilds, and more.
Refer to the module-level documentation for information on effectively using multiple shards, if you need to.
Note that there are additional methods available if you are manually managing a shard yourself, although they are hidden from the documentation since there are few use cases for doing such.
Stand-alone shards
You may instantiate a shard yourself - decoupled from the Client
- if
you need to. For most use cases, you will not need to do this, and you can
leave the client to do it.
This can be done by passing in the required parameters to Self::new
. You can
then manually handle the shard yourself.
Note: You really do not need to do this. Just call one of the
appropriate methods on the Client
.
Examples
See the documentation for Self::new
on how to use this.
Fields
client: WsStream
started: Instant
Instant of when the shard was started.
token: String
intents: GatewayIntents
Implementations
sourceimpl Shard
impl Shard
sourcepub async fn new(
ws_url: Arc<Mutex<String>>,
token: &str,
shard_info: [u64; 2],
intents: GatewayIntents
) -> Result<Shard>
pub async fn new(
ws_url: Arc<Mutex<String>>,
token: &str,
shard_info: [u64; 2],
intents: GatewayIntents
) -> Result<Shard>
Instantiates a new instance of a Shard, bypassing the client.
Note: You should likely never need to do this yourself.
Examples
Instantiating a new Shard manually for a bot with no shards, and then listening for events:
use std::sync::Arc;
use serenity::gateway::Shard;
use tokio::sync::Mutex;
let token = std::env::var("DISCORD_BOT_TOKEN")?;
// retrieve the gateway response, which contains the URL to connect to
let gateway = Arc::new(Mutex::new(http.get_gateway().await?.url));
let shard = Shard::new(gateway, &token, [0u64, 1u64], GatewayIntents::all()).await?;
// at this point, you can create a `loop`, and receive events and match
// their variants
Errors
On Error, will return either Error::Gateway
, Error::Tungstenite
or a Rustls/native TLS error.
sourcepub fn set_http(&mut self, http: Arc<Http>)
pub fn set_http(&mut self, http: Arc<Http>)
Sets the associated Http
client.
This will update the client’s application id after the shard receives a READY payload.
sourcepub fn current_presence(&self) -> &CurrentPresence
pub fn current_presence(&self) -> &CurrentPresence
Retrieves the current presence of the shard.
sourcepub fn heartbeat_instants(&self) -> &(Option<Instant>, Option<Instant>)
pub fn heartbeat_instants(&self) -> &(Option<Instant>, Option<Instant>)
Retrieves the heartbeat instants of the shard.
This is the time of when a heartbeat was sent and when an acknowledgement was last received.
sourcepub fn last_heartbeat_sent(&self) -> Option<&Instant>
pub fn last_heartbeat_sent(&self) -> Option<&Instant>
Retrieves the value of when the last heartbeat was sent.
sourcepub fn last_heartbeat_ack(&self) -> Option<&Instant>
pub fn last_heartbeat_ack(&self) -> Option<&Instant>
Retrieves the value of when the last heartbeat ack was received.
sourcepub async fn heartbeat(&mut self) -> Result<()>
pub async fn heartbeat(&mut self) -> Result<()>
Sends a heartbeat to the gateway with the current sequence.
This sets the last heartbeat time to now, and
Self::last_heartbeat_acknowledged
to false
.
Errors
Returns GatewayError::HeartbeatFailed
if there was an error sending
a heartbeat.
pub fn heartbeat_interval(&self) -> Option<&u64>
pub fn last_heartbeat_acknowledged(&self) -> bool
pub fn seq(&self) -> u64
pub fn session_id(&self) -> Option<&String>
pub fn set_activity(&mut self, activity: Option<Activity>)
pub fn set_presence(&mut self, status: OnlineStatus, activity: Option<Activity>)
pub fn set_status(&mut self, status: OnlineStatus)
sourcepub fn shard_info(&self) -> [u64; 2]
pub fn shard_info(&self) -> [u64; 2]
Retrieves a copy of the current shard information.
The first element is the current shard - 0-indexed - while the second element is the total number of shards – 1-indexed.
For example, if using 3 shards in total, and if this is shard 1, then it can be read as “the second of three shards”.
Examples
Retrieving the shard info for the second shard, out of two shards total:
For example, if using 3 shards in total, and if this is shard 1, then it can be read as “the second of three shards”.
Examples
Retrieving the shard info for the second shard, out of two shards total:
assert_eq!(shard.shard_info(), [1, 2]);
sourcepub fn stage(&self) -> ConnectionStage
pub fn stage(&self) -> ConnectionStage
Returns the current connection stage of the shard.
sourcepub async fn check_heartbeat(&mut self) -> bool
pub async fn check_heartbeat(&mut self) -> bool
Checks whether a heartbeat needs to be sent, as well as whether a heartbeat acknowledgement was received.
true
is returned under one of the following conditions:
- the heartbeat interval has not elapsed
- a heartbeat was successfully sent
- there is no known heartbeat interval yet
false
is returned under one of the following conditions:
- a heartbeat acknowledgement was not received in time
- an error occurred while heartbeating
sourcepub fn latency(&self) -> Option<StdDuration>
pub fn latency(&self) -> Option<StdDuration>
Calculates the heartbeat latency between the shard and the gateway.
sourcepub fn should_reconnect(&mut self) -> Option<ReconnectType>
pub fn should_reconnect(&mut self) -> Option<ReconnectType>
Performs a deterministic reconnect.
The type of reconnect is deterministic on whether a Self::session_id
.
If the session_id
still exists, then a RESUME is sent. If not, then
an IDENTIFY is sent.
Note that, if the shard is already in a stage of
ConnectionStage::Connecting
, then no action will be performed.
pub fn reconnection_type(&self) -> ReconnectType
sourcepub async fn chunk_guild(
&mut self,
guild_id: GuildId,
limit: Option<u16>,
filter: ChunkGuildFilter,
nonce: Option<&str>
) -> Result<()>
pub async fn chunk_guild(
&mut self,
guild_id: GuildId,
limit: Option<u16>,
filter: ChunkGuildFilter,
nonce: Option<&str>
) -> Result<()>
Requests that one or multiple Guild
s be chunked.
This will ask the gateway to start sending member chunks for large guilds (250 members+). If a guild is over 250 members, then a full member list will not be downloaded, and must instead be requested to be sent in “chunks” containing members.
Member chunks are sent as the Event::GuildMembersChunk
event. Each
chunk only contains a partial amount of the total members.
If the cache
feature is enabled, the cache will automatically be
updated with member chunks.
Examples
Chunk a single guild by Id, limiting to 2000 Member
s, and not
specifying a query parameter:
use serenity::model::id::GuildId;
shard.chunk_guild(GuildId(81384788765712384), Some(2000), ChunkGuildFilter::None, None).await?;
Chunk a single guild by Id, limiting to 20 members, and specifying a
query parameter of "do"
and a nonce of "request"
:
use serenity::model::id::GuildId;
shard
.chunk_guild(
GuildId(81384788765712384),
Some(20),
ChunkGuildFilter::Query("do".to_owned()),
Some("request"),
)
.await?;
sourcepub async fn identify(&mut self) -> Result<()>
pub async fn identify(&mut self) -> Result<()>
Sets the shard as going into identifying stage, which sets:
- the time that the last heartbeat sent as being now
- the
stage
toConnectionStage::Identifying
sourcepub async fn initialize(&mut self) -> Result<WsStream>
pub async fn initialize(&mut self) -> Result<WsStream>
Initializes a new WebSocket client.
This will set the stage of the shard before and after instantiation of the client.
pub async fn reset(&mut self)
pub async fn resume(&mut self) -> Result<()>
pub async fn reconnect(&mut self) -> Result<()>
pub async fn update_presence(&mut self) -> Result<()>
Auto Trait Implementations
impl !RefUnwindSafe for Shard
impl Send for Shard
impl Sync for Shard
impl Unpin for Shard
impl !UnwindSafe for Shard
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more