Struct serenity::client::bridge::gateway::ShardManager

pub struct ShardManager {
    pub runners: Arc<Mutex<HashMap<ShardId, ShardRunnerInfo>>>,
    /* private fields */
}

A manager for handling the status of shards by starting them, restarting them, and stopping them when required.

Note: The Client internally uses a shard manager. If you are using a Client, then you do not need to make one of these.

Examples

Initialize a shard manager with a framework responsible for shards 0 through 2, of 5 total shards:

use std::env;
use std::sync::Arc;

use serenity::client::bridge::gateway::{GatewayIntents, ShardManager, ShardManagerOptions};
use serenity::client::{EventHandler, RawEventHandler};
use serenity::framework::{Framework, StandardFramework};
use serenity::http::Http;
use serenity::prelude::*;
use serenity::CacheAndHttp;
use tokio::sync::{Mutex, RwLock};

struct Handler;

impl EventHandler for Handler {}
impl RawEventHandler for Handler {}

let gateway_url = Arc::new(Mutex::new(http.get_gateway().await?.url));
let data = Arc::new(RwLock::new(TypeMap::new()));
let event_handler = Arc::new(Handler) as Arc<dyn EventHandler>;
let framework =
    Arc::new(Box::new(StandardFramework::new()) as Box<dyn Framework + 'static + Send + Sync>);

ShardManager::new(ShardManagerOptions {
    data: &data,
    event_handler: &Some(event_handler),
    raw_event_handler: &None,
    framework: &framework,
    // the shard index to start initiating from
    shard_index: 0,
    // the number of shards to initiate (this initiates 0, 1, and 2)
    shard_init: 3,
    // the total number of shards in use
    shard_total: 5,
    ws_url: &gateway_url,
    intents: GatewayIntents::non_privileged(),
});

Fields

runners: Arc<Mutex<HashMap<ShardId, ShardRunnerInfo>>>

The shard runners currently managed.

Note: It is highly unrecommended to mutate this yourself unless you need to. Instead prefer to use methods on this struct that are provided where possible.

Implementations

impl ShardManager

pub async fn new(
    opt: ShardManagerOptions<'_>
) -> (Arc<Mutex<Self>>, ShardManagerMonitor)

Creates a new shard manager, returning both the manager and a monitor for usage in a separate thread.

pub async fn has(&self, shard_id: ShardId) -> bool

Returns whether the shard manager contains either an active instance of a shard runner responsible for the given ID.

If a shard has been queued but has not yet been initiated, then this will return false.

pub fn initialize(&mut self) -> Result<()>

Initializes all shards that the manager is responsible for.

This will communicate shard boots with the ShardQueuer so that they are properly queued.

pub async fn set_shards(&mut self, index: u64, init: u64, total: u64)

Sets the new sharding information for the manager.

This will shutdown all existing shards.

This will not instantiate the new shards.

pub async fn restart(&mut self, shard_id: ShardId)

Restarts a shard runner.

This sends a shutdown signal to a shard’s associated ShardRunner, and then queues a initialization of a shard runner for the same shard via the ShardQueuer.

Examples

Creating a client and then restarting a shard by ID:

(note: in reality this precise code doesn’t have an effect since the shard would not yet have been initialized via Self::initialize, but the concept is the same)

use std::env;

use serenity::client::bridge::gateway::ShardId;
use serenity::client::{Client, EventHandler};

struct Handler;

impl EventHandler for Handler {}

let token = std::env::var("DISCORD_TOKEN")?;
let mut client = Client::builder(&token).event_handler(Handler).await?;

// restart shard ID 7
client.shard_manager.lock().await.restart(ShardId(7)).await;

pub async fn shards_instantiated(&self) -> Vec<ShardId>

Returns the ShardIds of the shards that have been instantiated and currently have a valid ShardRunner.

pub async fn shutdown(&mut self, shard_id: ShardId, code: u16)

Attempts to shut down the shard runner by Id.

Returns a boolean indicating whether a shard runner was present. This is not necessary an indicator of whether the shard runner was successfully shut down.

Note: If the receiving end of an mpsc channel - theoretically owned by the shard runner - no longer exists, then the shard runner will not know it should shut down. This should never happen. It may already be stopped.

pub async fn shutdown_all(&mut self)

Sends a shutdown message for all shards that the manager is responsible for that are still known to be running.

If you only need to shutdown a select number of shards, prefer looping over the Self::shutdown method.

Trait Implementations

impl Debug for ShardManager

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

Formats the value using the given formatter.

impl Drop for ShardManager

fn drop(&mut self)

A custom drop implementation to clean up after the manager.

This shuts down all active ShardRunners and attempts to tell the ShardQueuer to shutdown.