Struct twilight_gateway::Shard

pub struct Shard(_);

Implementations

impl Shard

pub fn new(config: impl Into<ShardConfig>) -> Self

Creates a new shard, which will automatically connect to the gateway.

Examples

Create a new shard, wait a second, and then print its current connection stage:

use twilight_gateway::Shard;
use std::{env, time::Duration};
use tokio::time as tokio_time;

let mut shard = Shard::new(env::var("DISCORD_TOKEN")?);
shard.start().await?;

tokio_time::delay_for(Duration::from_secs(1)).await;

let info = shard.info().await?;
println!("Shard stage: {}", info.stage());

pub fn config(&self) -> &ShardConfig

Returns an immutable reference to the configuration used for this client.

pub async fn start<'_>(&'_ mut self) -> Result<()>

Start the shard, connecting it to the gateway and starting the process of receiving and processing events.

Errors

Errors if the ShardProcessor could not be started.

pub async fn events<'_>(&'_ self) -> impl Stream<Item = Event>

Creates a new stream of events from the shard.

There can be multiple streams of events. All events will be broadcast to all streams of events.

All event types except for EventType::SHARD_PAYLOAD are enabled. If you need to enable it, consider calling some_events instead.

pub async fn some_events<'_>(
    &'_ self,
    event_types: EventTypeFlags
) -> impl Stream<Item = Event>

Creates a new filtered stream of events from the shard.

Only the events specified in the bitflags will be sent over the stream.

Examples

Filter the events so that you only receive the Event::ShardConnected and Event::ShardDisconnected events:

use twilight_gateway::{EventTypeFlags, Event, Shard};
use futures::StreamExt;
use std::env;

let mut shard = Shard::new(env::var("DISCORD_TOKEN")?);
shard.start().await?;

let event_types = EventTypeFlags::SHARD_CONNECTED | EventTypeFlags::SHARD_DISCONNECTED;
let mut events = shard.some_events(event_types).await;

while let Some(event) = events.next().await {
    match event {
        Event::ShardConnected(_) => println!("Shard is now connected"),
        Event::ShardDisconnected(_) => println!("Shard is now disconnected"),
        // No other event will come in through the stream.
        _ => {},
    }
}

pub async fn info<'_>(&'_ self) -> Result<Information>

Returns information about the running of the shard, such as the current connection stage.

Errors

Returns Error::Shutdown if the shard isn't actively running.

pub fn session(&self) -> Result<Arc<Session>>

Returns a handle to the current session

Note

This session can be invalidated if it is kept around under a reconnect or resume. In consequence this call should not be cached.

Errors

Returns Error::Shutdown if the shard isn't actively running.

pub fn sink(&self) -> Result<ShardSink>

Returns an interface implementing the Sink trait which can be used to send messages.

Note

This call should not be cached for too long as it will be invalidated by reconnects and resumes.

Errors

Returns Error::Shutdown if the shard isn't actively running.

pub async fn command<'_, '_>(&'_ self, com: &'_ impl Serialize) -> Result<()>

Send a command over the gateway.

Errors

Fails if command could not be serialized, or if the command could not be sent.

Returns Error::Shutdown if the shard isn't actively running.

pub async fn shutdown<'_>(&'_ self)

Shuts down the shard.

This will cleanly close the connection, causing discord to end the session and show the bot offline

pub async fn shutdown_resumable<'_>(&'_ self) -> (u64, Option<ResumeSession>)

This will shut down the shard in a resumable way and return shard id and optional session info to resume with later if this shard is resumable

Trait Implementations

impl Clone for Shard

fn clone(&self) -> Shard

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Shard

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.