add token bucket example to Semaphore

tokio/src/sync/semaphore.rs

@@ -102,6 +102,79 @@ use std::sync::Arc;
 /// }
 /// ```
 ///
+/// Implement a simple token bucket for rate limiting
+///
+/// Many applications and systems have constraints on the rate at which certain
+/// operations should occur. Exceeding this rate can result in suboptimal
+/// performance or even errors.
+///
+/// The provided example uses a `TokenBucket`, implemented using a semaphore, that
+/// limits operations to a specific rate although token buckets allow short bursts that are faster
+/// than the allowed rate. The token bucket will be refilled after each interval. When the rate is exceeded,
+/// the `acquire` method will await until a token is available. Note that this implementation is suboptimal
+/// when the rate is large, because it consumes a lot of cpu constantly looping and sleeping.
+/// ```
+/// use std::sync::Arc;
+/// use tokio::sync::{AcquireError, Semaphore};
+/// use tokio::time::{interval, Duration};
+///
+/// struct TokenBucket {
+///     sem: Arc<Semaphore>,
+///     jh: tokio::task::JoinHandle<()>,
+/// }
+///
+/// impl TokenBucket {
+///     fn new(duration: Duration) -> Self {
+///         let rate = (1.0 / duration.as_secs_f32()) as usize;
+///         let sem = Arc::new(Semaphore::new(rate));
+///
+///         // refills the tokens at the end of each interval
+///         let jh = tokio::spawn({
+///             let sem = sem.clone();
+///             let mut interval = interval(duration);
+///             interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+///
+///             async move {
+///                 loop {
+///                     interval.tick().await;
+///
+///                     let cap = rate - sem.available_permits();
+///                     sem.add_permits(cap.min(1));
+///                 }
+///             }
+///         });
+///
+///         Self { jh, sem }
+///     }
+///
+///     async fn acquire(&self) -> Result<(), AcquireError> {
+///         self.sem.acquire().await.map(|p| p.forget())
+///     }
+///
+///     async fn close(self) {
+///         self.jh.abort();
+///         let _ = self.jh.await;
+///
+///         self.sem.close();
+///     }
+/// }
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let ops = 1.0; // operation per second
+///     let update_interval = 1.0 / ops;
+///     let bucket = TokenBucket::new(Duration::from_secs_f32(update_interval));
+///
+///     for _ in 0..5 {
+///         bucket.acquire().await.unwrap();
+///
+///         // do the operation
+///     }
+///
+///     bucket.close().await;
+/// }
+/// ```
+///
 /// [`PollSemaphore`]: https://docs.rs/tokio-util/latest/tokio_util/sync/struct.PollSemaphore.html
 /// [`Semaphore::acquire_owned`]: crate::sync::Semaphore::acquire_owned
 #[derive(Debug)]