Struct twilight_gateway::cluster::ClusterBuilder

pub struct ClusterBuilder(_, _);

Builder to configure and construct a Cluster.

Examples

Create a cluster with only the GUILD_MESSAGES intents with a large_threshold of 100.

use std::env;
use twilight_gateway::{Cluster, Intents};

let token = env::var("DISCORD_TOKEN")?;

let cluster = Cluster::builder(token, Intents::GUILD_MESSAGES)
    .large_threshold(100)?
    .build()
    .await?;

Implementations

impl ClusterBuilder

pub fn new(token: impl Into<String>, intents: Intents) -> Self

Create a new builder to construct and configure a cluster.

pub async fn build(self) -> Result<Cluster, ClusterStartError>

Consume the builder and create the cluster.

Errors

Returns ClusterStartError::RetrievingGatewayInfo if there was an HTTP error Retrieving the gateway information.

pub fn gateway_url(mut self: Self, gateway_url: Option<String>) -> Self

Set the URL that will be used to connect to the gateway.

pub fn http_client(mut self: Self, http_client: Client) -> Self

Set the twilight_http Client used by the cluster and the shards it manages.

This is needed so that the cluster and shards can retrieve gateway information.

Defaults to a new, default HTTP client is used.

pub fn large_threshold(
    mut self: Self,
    large_threshold: u64
) -> Result<Self, LargeThresholdError>

Set the "large threshold" of shards.

Refer to the shard's ShardBuilder::large_threshold for more information.

Errors

Returns LargeThresholdError::TooFew if the provided value is below 50.

Returns LargeThresholdError::TooMany if the provided value is above 250.

pub fn presence(mut self: Self, presence: UpdateStatusInfo) -> Self

Set the presence to use when identifying with the gateway.

Refer to the shard's ShardBuilder::presence for more information.

pub fn shard_scheme(mut self: Self, scheme: ShardScheme) -> Self

Set the scheme to use for shard managing.

For example, ShardScheme::Auto means that the cluster will automatically manage all of the shards that Discord recommends you use. ShardScheme::Range means that it will manage a range of shards, but not necessarily all of the shards that your bot uses.

The default value is ShardScheme::Auto. For most setups this is an acceptable default.

Examples

Configure a cluster to manage shards 0-9 out of 20 shards total:

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

let token = env::var("DISCORD_TOKEN")?;
let scheme = ShardScheme::try_from((0..=9, 20))?;

let cluster = Cluster::builder(token, Intents::GUILD_MESSAGES)
    .shard_scheme(scheme)
    .build()
    .await?;

pub fn queue(mut self: Self, queue: Arc<Box<dyn Queue>>) -> Self

Set the queue to use for queueing shard connections.

This is useful when you have a very large bot or when you have a more advanced setup with multiple processes connecting at the same time.

Refer to the queue module for more information.

pub fn resume_sessions(
    mut self: Self,
    resume_sessions: HashMap<u64, ResumeSession>
) -> Self

Set the session information to resume shards with.

This requires having recovered the resume data when shutting down the cluster via Cluster::down_resumable.

Note that this does not guarantee all or any of the shards will be able to resume. If their sessions are invalid they will have to re-identify to initialize a new session.

Trait Implementations

impl Debug for ClusterBuilder

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

Formats the value using the given formatter.

impl<T: Into<String>> From<(T, Intents)> for ClusterBuilder

pub fn from((token, intents): (T, Intents)) -> Self

Performs the conversion.