feat: autoposter handles!

Top-gg-Community · Dec 15, 2023 · bf841ab · bf841ab
1 parent 737a300
commit bf841ab
Show file tree

Hide file tree

Showing 7 changed files with 212 additions and 255 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "topgg"
-version = "1.2.0"
+version = "1.2.1"
 edition = "2021"
 authors = ["null (https://github.com/null8626)", "Top.gg <[email protected]> (https://top.gg)"]
 description = "The official Rust wrapper for the Top.gg API"

diff --git a/README.md b/README.md
@@ -164,9 +164,8 @@ async fn main() {
 
   // ... then in some on ready/new guild event ...
   let server_count = 12345;
-  autoposter
-    .feed(Stats::count_based(server_count, None))
-    .await;
+  let stats = Stats::count_based(server_count, None);
+  autoposter.feed(stats).await;
 }
 ```
 

diff --git a/src/autoposter.rs b/src/autoposter.rs
@@ -1,5 +1,5 @@
 use crate::{client::InnerClient, Stats};
-use core::{mem::MaybeUninit, time::Duration};
+use core::{mem::MaybeUninit, ops::Deref, time::Duration};
 use std::sync::Arc;
 use tokio::{
   sync::Mutex,
@@ -12,47 +12,103 @@ struct PendingData {
   stats: Stats,
 }
 
+/// A fully [`Clone`]able and thread-safe struct that lets you remotely feed bot statistics to the [`Autoposter`].
+pub struct AutoposterHandle {
+  data: Arc<Mutex<PendingData>>,
+}
+
+impl AutoposterHandle {
+  /// Feeds new bot stats to this autoposter handle. The [autoposter itself][Autoposter] will automatically post it to the [Top.gg](https://top.gg) servers once appropiate.
+  ///
+  /// # Examples
+  ///
+  /// Direct usage with an [`Autoposter`]:
+  ///
+  /// ```rust,no_run
+  /// use core::time::Duration;
+  /// use topgg::{Client, Stats};
+  ///
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  ///
+  /// // creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
+  /// // the autopost thread will stop once it's dropped.
+  /// let autoposter = client.new_autoposter(Duration::from_secs(1800));
+  ///
+  /// // ... then in some on ready/new guild event ...
+  /// let server_count = 12345;
+  /// let stats = Stats::count_based(server_count, None);
+  /// autoposter.feed(stats).await;
+  /// ```
+  ///
+  /// Remote usage with an [`AutoposterHandle`]:
+  ///
+  /// ```rust,no_run
+  /// use core::time::Duration;
+  /// use topgg::{Client, Stats};
+  ///
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  ///
+  /// // creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
+  /// // the autopost thread will stop once it's dropped.
+  /// let autoposter = client.new_autoposter(Duration::from_secs(1800));
+  ///
+  /// let server_count = 12345;
+  /// autoposter
+  ///   .feed(Stats::count_based(server_count, None))
+  ///   .await;
+  ///
+  /// // this handle can be cloned and tossed around threads!
+  /// let new_handle = autoposter.handle();
+  ///
+  /// // do the same thing...
+  /// new_handle
+  ///   .feed(Stats::count_based(server_count, None))
+  ///   .await;
+  ///
+  /// let another_handle = new_handle.clone();
+  ///
+  /// // do the same thing...
+  /// another_handle
+  ///   .feed(Stats::count_based(server_count, None))
+  ///   .await;
+  /// ```
+  pub async fn feed(&self, new_stats: Stats) {
+    let mut lock = self.data.lock().await;
+
+    lock.ready = true; // flag the PendingData object as containing new data.
+    lock.stats = new_stats;
+  }
+}
+
+/// Creates another handle that points to the same reference handle. Somewhat similar to an [`Arc::clone`].
+impl Clone for AutoposterHandle {
+  #[inline(always)]
+  fn clone(&self) -> Self {
+    Self {
+      data: Arc::clone(&self.data),
+    }
+  }
+}
+
 /// A struct that lets you automate the process of posting bot statistics to the [Top.gg API](https://docs.top.gg) in intervals.
-///
-/// # Examples
-///
-/// Basic usage:
-///
-/// ```rust,no_run
-/// use core::time::Duration;
-/// use topgg::{Client, Stats};
-///
-/// #[tokio::main]
-/// async fn main() {
-///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-///
-///   // creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
-///   // the autopost thread will stop once it's dropped.
-///   let autoposter = client.new_autoposter(Duration::from_secs(1800));
-///
-///   // ... then in some on ready/new guild event ...
-///   let server_count = 12345;
-///   autoposter
-///     .feed(Stats::count_based(server_count, None))
-///     .await;
-/// }
-/// ```
 #[must_use]
 pub struct Autoposter {
   thread: JoinHandle<()>,
-  data: Arc<Mutex<PendingData>>,
+  handle: AutoposterHandle,
 }
 
 impl Autoposter {
   #[allow(invalid_value, clippy::uninit_assumed_init)]
   pub(crate) fn new(client: Arc<InnerClient>, interval: Duration) -> Self {
     // SAFETY: post_stats will be called ONLY when the ready flag is set to true.
-    let current_thread_data = Arc::new(Mutex::new(PendingData {
-      ready: false,
-      stats: unsafe { MaybeUninit::uninit().assume_init() },
-    }));
+    let handle = AutoposterHandle {
+      data: Arc::new(Mutex::new(PendingData {
+        ready: false,
+        stats: unsafe { MaybeUninit::uninit().assume_init() },
+      })),
+    };
 
-    let thread_data = Arc::clone(&current_thread_data);
+    let thread_data = Arc::clone(&handle.data);
 
     Self {
       thread: spawn(async move {
@@ -67,40 +123,23 @@ impl Autoposter {
           }
         }
       }),
-      data: current_thread_data,
+      handle,
     }
   }
 
-  /// Feeds new bot stats to the autoposter. The autoposter will automatically post it to the [Top.gg](https://top.gg) servers in intervals.
-  ///
-  /// # Examples
-  ///
-  /// Basic usage:
-  ///
-  /// ```rust,no_run
-  /// use core::time::Duration;
-  /// use topgg::{Client, Stats};
-  ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///
-  ///   // creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
-  ///   // the autopost thread will stop once it's dropped.
-  ///   let autoposter = client.new_autoposter(Duration::from_secs(1800));
-  ///
-  ///   // ... then in some on ready/new guild event ...
-  ///   let server_count = 12345;
-  ///   autoposter
-  ///     .feed(Stats::count_based(server_count, None))
-  ///     .await;
-  /// }
-  /// ```
-  pub async fn feed(&self, new_stats: Stats) {
-    let mut lock = self.data.lock().await;
+  /// Creates an [`AutoposterHandle`] that lets you remotely feed bot statistics to this [`Autoposter`]. This struct is fully [`Clone`]able and thread-safe.
+  #[inline(always)]
+  pub fn handle(&self) -> AutoposterHandle {
+    self.handle.clone()
+  }
+}
 
-    lock.ready = true; // flag the PendingData object as containing new data.
-    lock.stats = new_stats;
+impl Deref for Autoposter {
+  type Target = AutoposterHandle;
+
+  #[inline(always)]
+  fn deref(&self) -> &Self::Target {
+    &self.handle
   }
 }
 

diff --git a/src/bot.rs b/src/bot.rs
@@ -120,14 +120,10 @@ impl Bot {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let bot = client.get_bot(264811613708746752).await.unwrap();
-  ///   
-  ///   println!("{}", bot.created_at());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let bot = client.get_bot(264811613708746752).await.unwrap();
+  ///
+  /// println!("{}", bot.created_at());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -146,14 +142,10 @@ impl Bot {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let bot = client.get_bot(264811613708746752).await.unwrap();
-  ///   
-  ///   println!("{}", bot.avatar());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let bot = client.get_bot(264811613708746752).await.unwrap();
+  ///
+  /// println!("{}", bot.avatar());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -170,14 +162,10 @@ impl Bot {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let bot = client.get_bot(264811613708746752).await.unwrap();
-  ///   
-  ///   println!("{}", bot.invite());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let bot = client.get_bot(264811613708746752).await.unwrap();
+  ///
+  /// println!("{}", bot.invite());
   /// ```
   #[must_use]
   pub fn invite(&self) -> String {
@@ -199,14 +187,10 @@ impl Bot {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let bot = client.get_bot(264811613708746752).await.unwrap();
-  ///   
-  ///   println!("{}", bot.shard_count());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let bot = client.get_bot(264811613708746752).await.unwrap();
+  ///
+  /// println!("{}", bot.shard_count());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -223,14 +207,10 @@ impl Bot {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let bot = client.get_bot(264811613708746752).await.unwrap();
-  ///   
-  ///   println!("{}", bot.url());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let bot = client.get_bot(264811613708746752).await.unwrap();
+  ///
+  /// println!("{}", bot.url());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -360,14 +340,10 @@ impl Stats {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let stats = client.get_stats().await.unwrap();
-  ///   
-  ///   println!("{:?}", stats.shards());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let stats = client.get_stats().await.unwrap();
+  ///
+  /// println!("{:?}", stats.shards());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -387,14 +363,10 @@ impl Stats {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let stats = client.get_stats().await.unwrap();
-  ///   
-  ///   println!("{:?}", stats.shard_count());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let stats = client.get_stats().await.unwrap();
+  ///
+  /// println!("{:?}", stats.shard_count());
   /// ```
   #[must_use]
   #[inline(always)]
@@ -414,14 +386,10 @@ impl Stats {
   /// ```rust,no_run
   /// use topgg::Client;
   ///
-  /// #[tokio::main]
-  /// async fn main() {
-  ///   let client = Client::new(env!("TOPGG_TOKEN").to_string());
-  ///   
-  ///   let stats = client.get_stats().await.unwrap();
-  ///   
-  ///   println!("{:?}", stats.server_count());
-  /// }
+  /// let client = Client::new(env!("TOPGG_TOKEN").to_string());
+  /// let stats = client.get_stats().await.unwrap();
+  ///
+  /// println!("{:?}", stats.server_count());
   /// ```
   #[must_use]
   pub fn server_count(&self) -> Option<usize> {