diff options
Diffstat (limited to 'src/client/bridge/gateway/mod.rs')
| -rw-r--r-- | src/client/bridge/gateway/mod.rs | 114 |
1 files changed, 104 insertions, 10 deletions
diff --git a/src/client/bridge/gateway/mod.rs b/src/client/bridge/gateway/mod.rs index 0b873aa..752b015 100644 --- a/src/client/bridge/gateway/mod.rs +++ b/src/client/bridge/gateway/mod.rs @@ -1,28 +1,113 @@ +//! The client gateway bridge is support essential for the [`client`] module. +//! +//! This is made available for user use if one wishes to be lower-level or avoid +//! the higher functionality of the [`Client`]. +//! +//! Of interest are three pieces: +//! +//! ### [`ShardManager`] +//! +//! The shard manager is responsible for being a clean interface between the +//! user and the shard runners, providing essential functions such as +//! [`ShardManager::shutdown`] to shutdown a shard and [`ShardManager::restart`] +//! to restart a shard. +//! +//! If you are using the `Client`, this is likely the only piece of interest to +//! you. Refer to [its documentation][`ShardManager`] for more information. +//! +//! ### [`ShardQueuer`] +//! +//! The shard queuer is a light wrapper around an mpsc receiver that receives +//! [`ShardManagerMessage`]s. It should be run in its own thread so it can +//! receive messages to start shards in a queue. +//! +//! Refer to [its documentation][`ShardQueuer`] for more information. +//! +//! ### [`ShardRunner`] +//! +//! The shard runner is responsible for actually running a shard and +//! communicating with its respective WebSocket client. +//! +//! It is performs all actions such as sending a presence update over the client +//! and, with the help of the [`Shard`], will be able to determine what to do. +//! This is, for example, whether to reconnect, resume, or identify with the +//! gateway. +//! +//! ### In Conclusion +//! +//! For almost every - if not every - use case, you only need to _possibly_ be +//! concerned about the [`ShardManager`] in this module. +//! +//! [`Client`]: ../../struct.Client.html +//! [`client`]: ../.. +//! [`Shard`]: ../../../gateway/struct.Shard.html +//! [`ShardManager`]: struct.ShardManager.html +//! [`ShardManager::restart`]: struct.ShardManager.html#method.restart +//! [`ShardManager::shutdown`]: struct.ShardManager.html#method.shutdown +//! [`ShardQueuer`]: struct.ShardQueuer.html +//! [`ShardRunner`]: struct.ShardRunner.html + mod shard_manager; +mod shard_manager_monitor; +mod shard_messenger; mod shard_queuer; mod shard_runner; +mod shard_runner_message; pub use self::shard_manager::ShardManager; +pub use self::shard_manager_monitor::ShardManagerMonitor; +pub use self::shard_messenger::ShardMessenger; pub use self::shard_queuer::ShardQueuer; pub use self::shard_runner::ShardRunner; +pub use self::shard_runner_message::ShardRunnerMessage; -use gateway::Shard; -use parking_lot::Mutex; use std::fmt::{Display, Formatter, Result as FmtResult}; use std::sync::mpsc::Sender; -use std::sync::Arc; -type Parked<T> = Arc<Mutex<T>>; -type LockedShard = Parked<Shard>; +/// A message either for a [`ShardManager`] or a [`ShardRunner`]. +/// +/// [`ShardManager`]: struct.ShardManager.html +/// [`ShardRunner`]: struct.ShardRunner.html +pub enum ShardClientMessage { + /// A message intended to be worked with by a [`ShardManager`]. + /// + /// [`ShardManager`]: struct.ShardManager.html + Manager(ShardManagerMessage), + /// A message intended to be worked with by a [`ShardRunner`]. + /// + /// [`ShardRunner`]: struct.ShardRunner.html + Runner(ShardRunnerMessage), +} +/// A message for a [`ShardManager`] relating to an operation with a shard. +/// +/// [`ShardManager`]: struct.ShardManager.html #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)] pub enum ShardManagerMessage { + /// Indicator that a [`ShardManagerMonitor`] should restart a shard. + /// + /// [`ShardManagerMonitor`]: struct.ShardManagerMonitor.html Restart(ShardId), + /// Indicator that a [`ShardManagerMonitor`] should fully shutdown a shard + /// without bringing it back up. + /// + /// [`ShardManagerMonitor`]: struct.ShardManagerMonitor.html Shutdown(ShardId), - #[allow(dead_code)] + /// Indicator that a [`ShardManagerMonitor`] should fully shutdown all shards + /// and end its monitoring process for the [`ShardManager`]. + /// + /// [`ShardManager`]: struct.ShardManager.html + /// [`ShardManagerMonitor`]: struct.ShardManagerMonitor.html ShutdownAll, } +/// A message to be sent to the [`ShardQueuer`]. +/// +/// This should usually be wrapped in a [`ShardClientMessage`]. +/// +/// [`ShardClientMessage`]: enum.ShardClientMessage.html +/// [`ShardQueuer`]: enum.ShardQueuer.html +#[derive(Clone, Debug)] pub enum ShardQueuerMessage { /// Message to start a shard, where the 0-index element is the ID of the /// Shard to start and the 1-index element is the total shards in use. @@ -31,8 +116,8 @@ pub enum ShardQueuerMessage { Shutdown, } -// A light tuplestruct wrapper around a u64 to verify type correctness when -// working with the IDs of shards. +/// A light tuplestruct wrapper around a u64 to verify type correctness when +/// working with the IDs of shards. #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)] pub struct ShardId(pub u64); @@ -42,7 +127,16 @@ impl Display for ShardId { } } +/// Information about a [`ShardRunner`]. +/// +/// The [`ShardId`] is not included because, as it stands, you probably already +/// know the Id if you obtained this. +/// +/// [`ShardId`]: struct.ShardId.html +/// [`ShardRunner`]: struct.ShardRunner.html +#[derive(Debug)] pub struct ShardRunnerInfo { - pub runner_tx: Sender<ShardManagerMessage>, - pub shard: Arc<Mutex<Shard>>, + /// The channel used to communicate with the shard runner, telling it + /// what to do with regards to its status. + pub runner_tx: Sender<ShardClientMessage>, } |