pub struct ShardManager {
pub runners: Arc<Mutex<HashMap<ShardId, ShardRunnerInfo>>>,
/* private fields */
}
client
and gateway
only.Expand description
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::{ShardManager, ShardManagerOptions};
use serenity::client::{EventHandler, RawEventHandler};
use serenity::framework::{Framework, StandardFramework};
use serenity::http::Http;
use serenity::model::gateway::GatewayIntents;
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(StandardFramework::new()) as Arc<dyn Framework + Send + Sync + 'static>;
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
sourceimpl ShardManager
impl ShardManager
sourcepub async fn new(
opt: ShardManagerOptions<'_>
) -> (Arc<Mutex<Self>>, ShardManagerMonitor)
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.
sourcepub async fn has(&self, shard_id: ShardId) -> bool
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
.
sourcepub fn initialize(&mut self) -> Result<()>
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.
sourcepub async fn set_shards(&mut self, index: u64, init: u64, total: u64)
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.
sourcepub async fn restart(&mut self, shard_id: ShardId)
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::prelude::*;
struct Handler;
impl EventHandler for Handler {}
let token = std::env::var("DISCORD_TOKEN")?;
let mut client =
Client::builder(&token, GatewayIntents::default()).event_handler(Handler).await?;
// restart shard ID 7
client.shard_manager.lock().await.restart(ShardId(7)).await;
sourcepub async fn shards_instantiated(&self) -> Vec<ShardId>
pub async fn shards_instantiated(&self) -> Vec<ShardId>
Returns the ShardId
s of the shards that have been instantiated and
currently have a valid ShardRunner
.
sourcepub async fn shutdown(&mut self, shard_id: ShardId, code: u16)
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.
sourcepub async fn shutdown_all(&mut self)
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
sourceimpl Debug for ShardManager
impl Debug for ShardManager
sourceimpl Drop for ShardManager
impl Drop for ShardManager
sourcefn drop(&mut self)
fn drop(&mut self)
A custom drop implementation to clean up after the manager.
This shuts down all active ShardRunner
s and attempts to tell the
ShardQueuer
to shutdown.
Auto Trait Implementations
impl !RefUnwindSafe for ShardManager
impl Send for ShardManager
impl Sync for ShardManager
impl Unpin for ShardManager
impl !UnwindSafe for ShardManager
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more