Struct twilight_gateway::cluster::Cluster

pub struct Cluster(_);

A manager for multiple shards.

The Cluster can be cloned and will point to the same cluster, so you can pass it around as needed.

Examples

Refer to the module-level documentation for examples.

Implementations

impl Cluster

pub async fn new(config: impl Into<ClusterConfig>) -> Result<Self>

Creates a new cluster from a configuration without bringing it up.

Errors

Returns Error::GettingGatewayInfo if there was an HTTP error getting the gateway information.

pub fn config(&self) -> &ClusterConfig

Returns an immutable reference to the configuration of this cluster.

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

Brings up the cluster, starting all of the shards that it was configured to manage.

Examples

Bring up a cluster, starting shards all 10 shards that a bot uses:

use twilight_gateway::cluster::{
    config::{ClusterConfig, ShardScheme},
    Cluster,
};
use std::{
    convert::TryFrom,
    env,
};

let scheme = ShardScheme::try_from((0..=9, 10))?;
let mut config = ClusterConfig::builder(env::var("DISCORD_TOKEN")?)
                        .shard_scheme(scheme)
                        .build();

let cluster = Cluster::new(config).await?;

// Finally, bring up the cluster.
cluster.up().await;

Errors

Returns Error::GettingGatewayInfo if the configured shard scheme is ShardScheme::Auto.

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

Brings down the cluster, stopping all of the shards that it's managing.

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

Brings down the cluster in a resumable way and returns all info needed for resuming

Note discord only allows resuming for a few minutes after disconnection. You can also not resume if you missed too many events already

pub async fn shard<'_>(&'_ self, id: u64) -> Option<Shard>

Returns a Shard by its ID.

pub async fn info<'_>(&'_ self) -> HashMap<u64, Information>

Returns information about all shards.

Examples

After waiting a minute, print the ID, latency, and stage of each shard:

use twilight_gateway::cluster::Cluster;
use std::{env, time::Duration};

let cluster = Cluster::new(env::var("DISCORD_TOKEN")?).await?;
cluster.up().await;

tokio::time::delay_for(Duration::from_secs(60)).await;

for (shard_id, info) in cluster.info().await {
    println!(
        "Shard {} is {} with an average latency of {:?}",
        shard_id,
        info.stage(),
        info.latency().average(),
    );
}

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

Send a command to the specified shard.

Errors

Fails if command could not be serialized or if the shard does not exist.

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

Returns a stream of events from all shards managed by this Cluster.

Each item in the stream contains both the shard's ID and the event itself.

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

Like events, but filters the events so that the stream consumer receives only the selected event types.

Examples

Retrieve a stream of events when a message is created, deleted, or updated:

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

let cluster = Cluster::new(env::var("DISCORD_TOKEN")?).await?;
cluster.up().await;

let types = EventTypeFlags::MESSAGE_CREATE
    | EventTypeFlags::MESSAGE_DELETE
    | EventTypeFlags::MESSAGE_UPDATE;
let mut events = cluster.some_events(types).await;

while let Some((shard_id, event)) = events.next().await {
    match event {
        Event::MessageCreate(_) => println!("Shard {} got a new message", shard_id),
        Event::MessageDelete(_) => println!("Shard {} got a deleted message", shard_id),
        Event::MessageUpdate(_) => println!("Shard {} got an updated message", shard_id),
        // No other events will come in through the stream.
        _ => {},
    }
}

Trait Implementations

impl Clone for Cluster

fn clone(&self) -> Cluster

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Cluster

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

Formats the value using the given formatter.