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

Code before:
///         // Kill the background task so it stops taking up resources when we
///         // don't need it anymore.
///         self.jh.abort();
///     }
/// }
///
/// #[tokio::main]
/// # async fn _hidden() {}
/// # #[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

Review comment (refactor):
I think the language here is somewhat complicated. I'd like to simplify it. For example:

> In some cases, running two tests in parallel may lead to problems. For example, this can happen when tests use the same database.

Code after:
///     // 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.
///     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.