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

Code before:
///
///         // Insert a key-value pair to database
///         let (key, value) = ("name", 0);
///         DB.insert((key, value)).await;
///
///         // Verify if the value has been inserted correctly.
///         assert_eq!(DB.get(key), value);
///
///         // Undo the insertation, make database status unchanged.
///         DB.delete(key).await;
///         // Permit automatically dropped here  
///     }
///     #[tokio::test]
///     async fn test_update() {
///         // Acquire permit first, wait until PERMIT can be acquired
///         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 if the value has been updated correctly.
///         assert_eq!(DB.get(key).await, new_value);
///         
///         // Undo any modificattion.
///         DB.delete(key).await;
///         // Permit automatically dropped here.  
///    }
///     #[tokio::test]
///     async fn test_others() {
///         // these tests can run in parallel with test_insert and test_update.
///         // They have nothing to do with PERMIT.
///     }
/// }
/// ```
///
/// ## 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

Review comment (suggestion):
Here, I would use the same comment as in `test_insert`.

Code after:
/// #    }
/// #    pub async fn delete(&self, key: &str) {
/// #        self.map.lock().await.remove(key);
/// #    }
/// #    pub async fn get(&self, key: &str) -> i32 {
/// #        *self.map.lock().await.get(key).unwrap()
/// #    }
/// # }
///
/// // Initialize a static semaphore with only one permit, which is used to
/// // prevent test_insert and test_update from running in parallel.
/// static PERMIT: Semaphore = Semaphore::const_new(1);
///
/// // Initialize the database that will be used by the subsequent tests.
/// static DB: Database = Database::setup();
///
/// #[tokio::test]
/// # async fn fake_test() {}
/// async fn test_insert() {
///     // 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 actual test stuff with database
///
///     // Insert a key-value pair to database
///     let (key, value) = ("name", 0);
///     DB.insert(key, value).await;
///
///     // Verify that the value has been inserted correctly.
///     assert_eq!(DB.get(key).await, value);
///
///     // Undo the insertion, so the database is empty at the end of the test.
///     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_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.