Remove client close handle

Remove the client's close handle. This was eclipsed by the
`client::bridge::gateway::ShardManager`, which is a public interface
giving full control over connected shards owned by the instance of the
client (as opposed to the purpose of the handle which was a simple
"shutdown" signal).

Additionally, more documentation has been added to
`Client::shard_manager`, now including a sample scenario of how to
shutdown the bot after some amount of time has passed.

Upgrade path:

Refer to the documentation for `Client::shard_manager` on a sample
scenario on how to switch from the close handle to the ShardManager.

1 files changed, 38 insertions, 19 deletions

diff --git a/src/client/mod.rs b/src/client/mod.rs
index 2980d58..6cba49a 100644
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -43,22 +43,12 @@ use parking_lot::Mutex;
 use self::bridge::gateway::{ShardManager, ShardManagerMonitor};
 use self::dispatch::dispatch;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, Ordering, ATOMIC_BOOL_INIT};
 use threadpool::ThreadPool;
 use typemap::ShareMap;
 
 #[cfg(feature = "framework")]
 use framework::Framework;
 
-static HANDLE_STILL: AtomicBool = ATOMIC_BOOL_INIT;
-
-#[derive(Copy, Clone)]
-pub struct CloseHandle;
-
-impl CloseHandle {
-    pub fn close(self) { HANDLE_STILL.store(false, Ordering::Relaxed); }
-}
-
 /// The Client is the way to be able to start sending authenticated requests
 /// over the REST API, as well as initializing a WebSocket connection through
 /// [`Shard`]s. Refer to the [documentation on using sharding][sharding docs]
@@ -238,6 +228,44 @@ pub struct Client {
     /// # }
     /// ```
     ///
+    /// Shutting down all connections after one minute of operation:
+    ///
+    /// ```rust,no_run
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// use serenity::client::{Client, EventHandler};
+    /// use std::time::Duration;
+    /// use std::{env, thread};
+    ///
+    /// struct Handler;
+    ///
+    /// impl EventHandler for Handler { }
+    ///
+    /// let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;
+    ///
+    /// // Create a clone of the `Arc` containing the shard manager.
+    /// let shard_manager = client.shard_manager.clone();
+    ///
+    /// // Create a thread which will sleep for 60 seconds and then have the
+    /// // shard manager shutdown.
+    /// thread::spawn(move || {
+    ///     thread::sleep(Duration::from_secs(60));
+    ///
+    ///     shard_manager.lock().shutdown_all();
+    ///
+    ///     println!("Shutdown shard manager!");
+    /// });
+    ///
+    /// println!("Client shutdown: {:?}", client.start());
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
+    /// ```
+    ///
     /// [`Client::start_shard`]: #method.start_shard
     /// [`Client::start_shards`]: #method.start_shards
     pub shard_manager: Arc<Mutex<ShardManager>>,
@@ -769,9 +797,6 @@ impl Client {
         self.start_connection([range[0], range[1], total_shards])
     }
 
-    /// Returns a thread-safe handle for closing shards.
-    pub fn close_handle(&self) -> CloseHandle { CloseHandle }
-
     // Shard data layout is:
     // 0: first shard number to initialize
     // 1: shard number to initialize up to and including
@@ -786,8 +811,6 @@ impl Client {
     //
     // [`ClientError::Shutdown`]: enum.ClientError.html#variant.Shutdown
     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.
         //
         // This also acts as a form of check to ensure the token is correct.
@@ -830,10 +853,6 @@ impl Client {
     }
 }
 
-impl Drop for Client {
-    fn drop(&mut self) { self.close_handle().close(); }
-}
-
 /// Validates that a token is likely in a valid format.
 ///
 /// This performs the following checks on a given token: