Redo client internals + gateway

This commit is a rewrite of the client module's internals and the
gateway.

The main benefit of this is that there is either 0 or 1 lock retrievals
per event received, and the ability to utilize the ShardManager both
internally and in userland code has been improved.

The primary rework is in the `serenity::client` module, which now
includes a few more structures, some changes to existing ones, and more
functionality (such as to the `ShardManager`).

The two notable additions to the client-gateway bridge are the
`ShardMessenger` and `ShardManagerMonitor`.

The `ShardMessenger` is a simple-to-use interface for users to use to
interact with shards. The user is given one of these in the
`serenity::client::Context` in dispatches to the
`serenity::client::EventHandler`. This can be used for updating the
presence of a shard, sending a guild chunk message, or sending a user's
defined WebSocket message.

The `ShardManagerMonitor` is a loop run in its own thread, potentially
the main thread, that is responsible for receiving messages over an mpsc
channel on what to do with shards via the `ShardManager`. For example,
it will receive a message to shutdown a single shard, restart a single
shard, or shutdown the entire thing.

Users, in most applications, will not interact with the
`ShardManagerMonitor`. Users using the `serenity::client::Client`
interact with only the `ShardMessenger`.

The `ShardManager` is now usable by the user and is available to them,
and contains public functions for shutdowns, initializations, restarts,
and complete shutdowns of shards. It contains utility functions like
determining whether the `ShardManager` is responsible for a shard of a
given ID and the IDs of shards currently active (having an associated
`ShardRunner`). It can be found on
`serenity::client::Client::shard_manager`.

Speaking of the `ShardRunner`, it no longer owns a clone of an Arc to
its assigned `serenity::gateway::Shard`. It now completely owns the
Shard. This means that in order to open the shard, a `ShardRunner` no
longer has to repeatedly retrieve a lock to it. This reduces the number
of lock retrievals per event dispatching cycle from 3 or 4 depending on
event type to 0 or 1 depending on whether it's a message create _and_ if
the framework is in use. To interact with the Shard, one must now go
through the previously mentioned `ShardMessenger`, which the
`ShardRunner` will check for messages from on a loop.

`serenity::client::Context` is now slightly different. Instead of the
`shard` field being `Arc<Mutex<Shard>>`, it is an instance of a
`ShardMessenger`. The interface is the same (minus losing some
Shard-specific methods like `latency`), and `Context`'s shortcuts still
exist (like `Context::online` or `Context::set_game`). It now
additionally includes a `Context::shard_id` field which is a u64
containing the ID of the shard that the event was dispatched from.

`serenity::client::Client` has one changed field name, one field that is
now public, and a new field. `Client::shard_runners` is now
`Client::shard_manager` of type `Arc<Mutex<ShardManager>>`. The
`Client::token` field is now public. This can, for example, be mutated
on token resets if you know what you're doing. `Client::ws_uri` is new
and contains the URI for shards to use when connecting to the gateway.
Otherwise, the Client's usage is unchanged.

`serenity::gateway::Shard` has a couple of minor changes and many more
public methods and fields. The `autoreconnect`, `check_heartbeat`,
`handle_event`, `heartbeat`, `identify`, `initialize`, `reset`,
`resume`, `reconnect`, and `update_presence` methods are now public. The
`token` structfield is now public. There are new getters for various
structfields, such as `heartbeat_instants` and `last_heartbeat_ack`.
The breaking change on the `Shard` is that `Shard::handle_event` now
takes an event by reference and, instead of returning
`Result<Option<Event>>`, it now returns `Result<Option<ShardAction>>`.

`serenity::gateway::ShardAction` is a light enum determining an action
that someone _should_/_must_ perform on the shard, e.g. reconnecting or
identifying. This is determined by `Shard::handle_event`.

In total, there aren't too many breaking changes that most of userland
use cases has to deal with -- at most, changing some usage of `Context`.
Retrieving information like a Shard's latency is currently not possible
anymore but work will be done to make this functionality available
again.

1 files changed, 86 insertions, 56 deletions

diff --git a/src/client/mod.rs b/src/client/mod.rs
index 00a305a..2a97c91 100644
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -37,13 +37,11 @@ pub use http as rest;
 #[cfg(feature = "cache")]
 pub use CACHE;
 
-use self::bridge::gateway::{ShardId, ShardManager, ShardRunnerInfo};
+use self::bridge::gateway::{ShardManager, ShardManagerMonitor};
 use self::dispatch::dispatch;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering, ATOMIC_BOOL_INIT};
 use parking_lot::Mutex;
-use std::collections::HashMap;
-use std::mem;
 use threadpool::ThreadPool;
 use typemap::ShareMap;
 use http;
@@ -103,8 +101,7 @@ impl CloseHandle {
 /// [`on_message`]: #method.on_message
 /// [`Event::MessageCreate`]: ../model/event/enum.Event.html#variant.MessageCreate
 /// [sharding docs]: gateway/index.html#sharding
-#[derive(Clone)]
-pub struct Client<H: EventHandler + Send + Sync + 'static> {
+pub struct Client {
     /// A ShareMap which requires types to be Send + Sync. This is a map that
     /// can be safely shared across contexts.
     ///
@@ -191,7 +188,6 @@ pub struct Client<H: EventHandler + Send + Sync + 'static> {
     ///
     /// [`Event::Ready`]: ../model/event/enum.Event.html#variant.Ready
     /// [`on_ready`]: #method.on_ready
-    event_handler: Arc<H>,
     #[cfg(feature = "framework")] framework: Arc<Mutex<Option<Box<Framework + Send>>>>,
     /// A HashMap of all shards instantiated by the Client.
     ///
@@ -224,12 +220,12 @@ pub struct Client<H: EventHandler + Send + Sync + 'static> {
     ///
     /// let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;
     ///
-    /// let shard_runners = client.shard_runners.clone();
+    /// let shard_manager = client.shard_manager.clone();
     ///
     /// thread::spawn(move || {
     ///     loop {
     ///         println!("Shard count instantiated: {}",
-    ///                  shard_runners.lock().len());
+    ///                  shard_manager.lock().shards_instantiated().len());
     ///
     ///         thread::sleep(Duration::from_millis(5000));
     ///     }
@@ -244,16 +240,26 @@ pub struct Client<H: EventHandler + Send + Sync + 'static> {
     ///
     /// [`Client::start_shard`]: #method.start_shard
     /// [`Client::start_shards`]: #method.start_shards
-    pub shard_runners: Arc<Mutex<HashMap<ShardId, ShardRunnerInfo>>>,
+    pub shard_manager: Arc<Mutex<ShardManager>>,
+    shard_manager_worker: ShardManagerMonitor,
     /// The threadpool shared by all shards.
     ///
     /// Defaults to 5 threads, which should suffice small bots. Consider
     /// increasing this number as your bot grows.
     pub threadpool: ThreadPool,
-    token: Arc<Mutex<String>>,
+    /// The token in use by the client.
+    pub token: Arc<Mutex<String>>,
+    /// URI that the client's shards will use to connect to the gateway.
+    ///
+    /// This is likely not important for production usage and is, at best, used
+    /// for debugging.
+    ///
+    /// This is wrapped in an `Arc<Mutex<T>>` so all shards will have an updated
+    /// value available.
+    pub ws_uri: Arc<Mutex<String>>,
 }
 
-impl<H: EventHandler + Send + Sync + 'static> Client<H> {
+impl Client {
     /// Creates a Client for a bot user.
     ///
     /// Discord has a requirement of prefixing bot tokens with `"Bot "`, which
@@ -283,7 +289,8 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     /// #    try_main().unwrap();
     /// # }
     /// ```
-    pub fn new(token: &str, handler: H) -> Result<Self> {
+    pub fn new<H>(token: &str, handler: H) -> Result<Self>
+        where H: EventHandler + Send + Sync + 'static {
         let token = if token.starts_with("Bot ") {
             token.to_string()
         } else {
@@ -295,23 +302,53 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
 
         let name = "serenity client".to_owned();
         let threadpool = ThreadPool::with_name(name, 5);
+        let url = Arc::new(Mutex::new(http::get_gateway()?.url));
+        let data = Arc::new(Mutex::new(ShareMap::custom()));
+        let event_handler = Arc::new(handler);
 
         Ok(feature_framework! {{
+            let framework = Arc::new(Mutex::new(None));
+
+            let (shard_manager, shard_manager_worker) = ShardManager::new(
+                0,
+                0,
+                0,
+                Arc::clone(&url),
+                Arc::clone(&locked),
+                Arc::clone(&data),
+                Arc::clone(&event_handler),
+                Arc::clone(&framework),
+                threadpool.clone(),
+            );
+
             Client {
-                data: Arc::new(Mutex::new(ShareMap::custom())),
-                event_handler: Arc::new(handler),
                 framework: Arc::new(Mutex::new(None)),
-                shard_runners: Arc::new(Mutex::new(HashMap::new())),
-                threadpool,
                 token: locked,
+                ws_uri: url,
+                data,
+                shard_manager,
+                shard_manager_worker,
+                threadpool,
             }
         } else {
+            let (shard_manager, shard_manager_worker) = ShardManager::new(
+                0,
+                0,
+                0,
+                Arc::clone(&url),
+                locked.clone(),
+                data.clone(),
+                Arc::clone(&event_handler),
+                threadpool.clone(),
+            );
+
             Client {
-                data: Arc::new(Mutex::new(ShareMap::custom())),
-                event_handler: Arc::new(handler),
-                shard_runners: Arc::new(Mutex::new(HashMap::new())),
-                threadpool,
                 token: locked,
+                ws_uri: url,
+                data,
+                shard_manager,
+                shard_manager_worker,
+                threadpool,
             }
         }})
     }
@@ -462,7 +499,7 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     ///
     /// [gateway docs]: gateway/index.html#sharding
     pub fn start(&mut self) -> Result<()> {
-        self.start_connection([0, 0, 1], http::get_gateway()?.url)
+        self.start_connection([0, 0, 1])
     }
 
     /// Establish the connection(s) and start listening for events.
@@ -514,15 +551,13 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     /// [`ClientError::Shutdown`]: enum.ClientError.html#variant.Shutdown
     /// [gateway docs]: gateway/index.html#sharding
     pub fn start_autosharded(&mut self) -> Result<()> {
-        let mut res = http::get_bot_gateway()?;
-
-        let x = res.shards as u64 - 1;
-        let y = res.shards as u64;
-        let url = mem::replace(&mut res.url, String::default());
+        let (x, y) = {
+            let res = http::get_bot_gateway()?;
 
-        drop(res);
+            (res.shards as u64 - 1, res.shards as u64)
+        };
 
-        self.start_connection([0, x, y], url)
+        self.start_connection([0, x, y])
     }
 
     /// Establish a sharded connection and start listening for events.
@@ -603,7 +638,7 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     /// [`start_autosharded`]: #method.start_autosharded
     /// [gateway docs]: gateway/index.html#sharding
     pub fn start_shard(&mut self, shard: u64, shards: u64) -> Result<()> {
-        self.start_connection([shard, shard, shards], http::get_gateway()?.url)
+        self.start_connection([shard, shard, shards])
     }
 
     /// Establish sharded connections and start listening for events.
@@ -657,10 +692,7 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     /// [`start_shard_range`]: #method.start_shard_range
     /// [Gateway docs]: gateway/index.html#sharding
     pub fn start_shards(&mut self, total_shards: u64) -> Result<()> {
-        self.start_connection(
-            [0, total_shards - 1, total_shards],
-            http::get_gateway()?.url,
-        )
+        self.start_connection([0, total_shards - 1, total_shards])
     }
 
     /// Establish a range of sharded connections and start listening for events.
@@ -730,7 +762,7 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     /// [`start_shards`]: #method.start_shards
     /// [Gateway docs]: gateway/index.html#sharding
     pub fn start_shard_range(&mut self, range: [u64; 2], total_shards: u64) -> Result<()> {
-        self.start_connection([range[0], range[1], total_shards], http::get_gateway()?.url)
+        self.start_connection([range[0], range[1], total_shards])
     }
 
     /// Returns a thread-safe handle for closing shards.
@@ -749,7 +781,7 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
     // an error.
     //
     // [`ClientError::Shutdown`]: enum.ClientError.html#variant.Shutdown
-    fn start_connection(&mut self, shard_data: [u64; 3], url: String) -> Result<()> {
+    fn start_connection(&mut self, shard_data: [u64; 3]) -> Result<()> {
         HANDLE_STILL.store(true, Ordering::Relaxed);
 
         // Update the framework's current user if the feature is enabled.
@@ -764,39 +796,37 @@ impl<H: EventHandler + Send + Sync + 'static> Client<H> {
             }
         }
 
-        let gateway_url = Arc::new(Mutex::new(url));
+        {
+            let mut manager = self.shard_manager.lock();
+
+            let init = shard_data[1] - shard_data[0] + 1;
 
-        let mut manager = ShardManager::new(
-            shard_data[0],
-            shard_data[1] - shard_data[0] + 1,
-            shard_data[2],
-            Arc::clone(&gateway_url),
-            Arc::clone(&self.token),
-            Arc::clone(&self.data),
-            Arc::clone(&self.event_handler),
-            #[cfg(feature = "framework")]
-            Arc::clone(&self.framework),
-            self.threadpool.clone(),
-        );
+            manager.set_shards(shard_data[0], init, shard_data[2]);
 
-        self.shard_runners = Arc::clone(&manager.runners);
+            debug!(
+                "Initializing shard info: {} - {}/{}",
+                shard_data[0],
+                init,
+                shard_data[2],
+            );
 
-        if let Err(why) = manager.initialize() {
-            error!("Failed to boot a shard: {:?}", why);
-            info!("Shutting down all shards");
+            if let Err(why) = manager.initialize() {
+                error!("Failed to boot a shard: {:?}", why);
+                info!("Shutting down all shards");
 
-            manager.shutdown_all();
+                manager.shutdown_all();
 
-            return Err(Error::Client(ClientError::ShardBootFailure));
+                return Err(Error::Client(ClientError::ShardBootFailure));
+            }
         }
 
-        manager.run();
+        self.shard_manager_worker.run();
 
         Err(Error::Client(ClientError::Shutdown))
     }
 }
 
-impl<H: EventHandler + Send + Sync + 'static> Drop for Client<H> {
+impl Drop for Client {
     fn drop(&mut self) { self.close_handle().close(); }
 }