Struct twilight_gateway::stream::ShardRef
source · pub struct ShardRef<'a> { /* private fields */ }Expand description
Guard dereferencing to the shard that produced an event or message.
Note that manually causing the destructor to not be called will cause the shard to not be re-inserted into the stream.
Methods from Deref<Target = Shard>§
sourcepub fn config(&self) -> &Config
pub fn config(&self) -> &Config
Immutable reference to the configuration used to instantiate this shard.
sourcepub fn inflater(&self) -> &Inflater
Available on crate features zlib-stock or zlib-simd only.
pub fn inflater(&self) -> &Inflater
zlib-stock or zlib-simd only.Zlib decompressor statistics.
Reset when reconnecting to the gateway.
sourcepub fn status(&self) -> &ConnectionStatus
pub fn status(&self) -> &ConnectionStatus
Connection status of the shard.
sourcepub fn latency(&self) -> &Latency
pub fn latency(&self) -> &Latency
Shard latency statistics, including average latency and recent heartbeat latency times.
Reset when reconnecting to the gateway.
sourcepub fn ratelimiter(&self) -> Option<&CommandRatelimiter>
pub fn ratelimiter(&self) -> Option<&CommandRatelimiter>
Statistics about the number of available commands and when the command ratelimiter will refresh.
This won’t be present if ratelimiting was disabled via
ConfigBuilder::ratelimit_messages or if the shard is disconnected.
sourcepub fn session(&self) -> Option<&Session>
pub fn session(&self) -> Option<&Session>
Immutable reference to the active gateway session.
An active session may not be present if the shard had its session invalidated and has not yet reconnected.
sourcepub async fn next_event(&mut self) -> Result<Event, ReceiveMessageError>
pub async fn next_event(&mut self) -> Result<Event, ReceiveMessageError>
Wait for the next Discord event from the gateway.
This is a convenience method that internally calls next_message and
only returns wanted Events, configured via
ConfigBuilder::event_types. Close messages are always considered
wanted and map onto the Event::GatewayClose variant.
Events not registered in Twilight are skipped. If you need to receive
events Twilight doesn’t support, use next_message to receive raw
payloads.
Errors
Returns a ReceiveMessageErrorType::Compression error type if the
message payload failed to decompress.
Returns a ReceiveMessageErrorType::Deserializing error type if the
message payload failed to deserialize.
Returns a ReceiveMessageErrorType::FatallyClosed error type if the
shard was closed due to a fatal error, such as invalid authorization.
Returns a ReceiveMessageErrorType::Process error type if the shard
failed to internally process a received event.
Returns a ReceiveMessageErrorType::Reconnect error type if the shard
failed to reconnect to the gateway. This isn’t a fatal error and can be
retried.
Returns a ReceiveMessageErrorType::SendingMessage error type if the
shard failed to send a message to the gateway, such as a heartbeat.
sourcepub async fn next_message(&mut self) -> Result<Message, ReceiveMessageError>
pub async fn next_message(&mut self) -> Result<Message, ReceiveMessageError>
Wait for the next raw message from the websocket connection.
Errors
Returns a ReceiveMessageErrorType::Compression error type if the
message payload failed to decompress.
Returns a ReceiveMessageErrorType::FatallyClosed error type if the
shard was closed due to a fatal error, such as invalid authorization.
Returns a ReceiveMessageErrorType::Process error type if the shard
failed to internally process a received event.
Returns a ReceiveMessageErrorType::Reconnect error type if the shard
failed to reconnect to the gateway. This isn’t a fatal error and can be
retried.
Returns a ReceiveMessageErrorType::SendingMessage error type if the
shard failed to send a message to the gateway, such as a heartbeat.
sourcepub async fn command(&mut self, command: &impl Command) -> Result<(), SendError>
pub async fn command(&mut self, command: &impl Command) -> Result<(), SendError>
Send a command over the gateway.
Serializes the command and then calls send.
Examples
Request members whose names start with “tw” in a guild:
use std::env;
use twilight_gateway::{ConnectionStatus, Intents, Shard, ShardId};
use twilight_model::{gateway::payload::outgoing::RequestGuildMembers, id::Id};
let intents = Intents::GUILD_VOICE_STATES;
let token = env::var("DISCORD_TOKEN")?;
let mut shard = Shard::new(ShardId::ONE, token, intents);
// Discord only allows sending the `RequestGuildMembers` command after
// the shard is identified.
while !shard.status().is_identified() {
// Ignore these messages.
shard.next_message().await?;
}
// Query members whose names start with "tw" and limit the results to 10
// members.
let request = RequestGuildMembers::builder(Id::new(1)).query("tw", Some(10));
// Send the request over the shard.
shard.command(&request).await?;Errors
Returns a SendErrorType::Sending error type if the command could
not be sent over the websocket. This indicates the shard is either
currently restarting or closed and will restart.
Returns a SendErrorType::Serializing error type if the provided
command failed to serialize.
sourcepub async fn send(&mut self, json: String) -> Result<(), SendError>
pub async fn send(&mut self, json: String) -> Result<(), SendError>
Send a JSON encoded gateway event.
A permit from the shard’s ratelimiter is first awaited (if ratelimiting is enabled) before sending the event.
Errors
Returns a SendErrorType::Sending error type if the event could not
be sent over the websocket. This indicates the shard is either currently
restarting or closed and will restart.
sourcepub fn sender(&self) -> MessageSender
pub fn sender(&self) -> MessageSender
Retrieve a channel to send outgoing gateway events over the shard to the gateway.
This is primarily useful for sending to other tasks and threads where the shard won’t be available.
sourcepub async fn close(
&mut self,
close_frame: CloseFrame<'static>
) -> Result<Option<Session>, SendError>
pub async fn close( &mut self, close_frame: CloseFrame<'static> ) -> Result<Option<Session>, SendError>
Send a Websocket close frame indicating whether to also invalidate the shard’s session.
Returns the shard’s session if the close frame code is not 1000 or
1001, which invalidates the session and shows the application’s bot as
offline. Otherwise Discord will not invalidate the shard’s session and
will continue to show the application’s bot as online until its presence
times out.
Sets status to ConnectionStatus::Disconnected with the close_code
from the close_frame.
To read all remaining events, continue calling Shard::next_message
until it returns the response close message or a
ReceiveMessageErrorType::Io error type.
You do not need to call this method upon receiving a close message, Twilight automatically responds for you.
Example
Close the gateway connection but process already received messages:
use twilight_gateway::{error::ReceiveMessageErrorType, CloseFrame, Message};
shard.close(CloseFrame::NORMAL).await?;
loop {
match shard.next_message().await {
Ok(Message::Close(_)) => {
// We've now received a close message response from the
// Gateway.
// Further calls to `next_message` would cause a reconnect.
break;
}
Ok(Message::Text(_)) => unimplemented!("handle message"),
Err(source) if matches!(source.kind(), ReceiveMessageErrorType::Io) => break,
Err(source) => tracing::warn!(?source, "error receiving message"),
}
}Errors
Returns a SendErrorType::Sending error type if the close frame could
not be sent over the websocket. This indicates the shard is either
currently restarting or closed and will restart.