Repository: tokio-rs/tokio
File: tokio/src/sync/semaphore.rs (Rust)

Code before:
/// # #[tokio::main(flavor = "current_thread", start_paused = true)]
/// async fn main() {
///     let capacity = 5;
///     let update_interval = Duration::from_secs_f32(1.0 / capacity as f32);
///     let bucket = TokenBucket::new(update_interval, capacity);
///
///     for _ in 0..5 {
///         bucket.acquire().await;
///
///         // do the operation
///     }
/// }
/// ```
///
/// ## Ensure Tests with Mutual Dependencies Run Sequentially
///
/// By default, Rust runs tests concurrently. However, in some scenarios, concurrent execution might lead to test interference.
/// For example, multiple tests might communicate with the same database, necessitating sequential execution to prevent data conflicts.
///
/// Consider the following scenario:
/// 1. `test_insert`: Inserts a key-value pair into the database, then retrieves the value using the same key to verify the insertion.
/// 2. `test_update`: After insertion, this test updates the key's value to a new one and verifies if the value has been accurately updated.
/// 3. `test_others`: This is a non-interfering test that can run concurrently with other tests.
///
/// For this example, it's essential that `test_insert` and `test_update` run sequentially, though their execution order is inconsequential.
/// Leveraging a semaphore with a single permit elegantly addresses this challenge.
///
/// ```
/// #[cfg(test)]
/// mod tests {
///    use tokio::sync::Semaphore;
///    // only one permit can be acquired
///    static PERMIT: Semaphore = Semaphore::const_new(1);
///    // initilization of database
///    static DB: database = database::setup();
///    #[tokio::test]
///    async fn test_insert() {
///        // acquire permit first
///         let permit = PERMIT.acquire().await.unwrap();
///         let (key, value) = ("name", 0);
///         DB.insert((key, value)).await;
///         assert_eq!(DB.get(key), value);
///         // undo the modification
///         DB.delete(key).await;
///         // permit dropped here
///     }
///     #[tokio::test]
///     async fn test_update() {
///         let permit = PERMIT.acquire().await.unwrap();
///         let (key, value) = ("name", 0);
///         DB.insert((key, value)).await;

Review comment (suggestion):
The language here is also complicated. Please try to rephrase "non-interfering" and "their execution order is inconsequential" to something simpler.

Code after:
/// # async fn fake_test() {}
/// async fn test_update() {
///     // Acquire permit before proceeding. Since the semaphore has only one permit,
///     // the test will wait if the permit is already acquired by other tests.
///     let permit = PERMIT.acquire().await.unwrap();
///
///     // Do the same insert.
///     let (key, value) = ("name", 0);
///     DB.insert(key, value).await;
///
///     // Update the existing value with a new one.
///     let new_value = 1;
///     DB.update(key, new_value).await;
///
///     // Verify that the value has been updated correctly.
///     assert_eq!(DB.get(key).await, new_value);
///
///     // Undo any modificattion.
///     DB.delete(key).await;
///
///     // Drop permit. This allows the other test to start running.
///     drop(permit);
/// }
///
/// #[tokio::test]
/// # async fn fake_test() {}
/// async fn test_others() {
///     // This test can run in parallel with test_insert and test_update,
///     // so it does not use PERMIT.
/// }
/// # #[tokio::main]
/// # async fn main() {
/// #   test_insert().await;
/// #   test_update().await;
/// #   test_others().await;
/// # }
/// ```
///
/// ## Rate limiting using a token bucket
///
/// 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.
///
/// This example implements rate limiting using a [token bucket]. A token bucket is a form of rate
/// limiting that doesn't kick in immediately, to allow for short bursts of incoming requests that
/// arrive at the same time.
///
/// With a token bucket, each incoming request consumes a token, and the tokens are refilled at a
/// certain rate that defines the rate limit. When a burst of requests arrives, tokens are
/// immediately given out until the bucket is empty. Once the bucket is empty, requests will have to