docs: add semaphore example

Signed-off-by: Muhan Song <songmuhan@stu.pku.edu.cn>

tokio/src/sync/semaphore.rs

@@ -123,6 +123,91 @@ use std::sync::Arc;
 /// # }
 /// ```
 ///
+/// ## Prevent tests from running in parallel
+///
+/// By default, Rust runs tests in the same file in parallel. However, in some cases, running two tests in parallel may lead to problems.
+/// For example, this can happen when tests use the same database.
+///
+/// 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`: Inserts a key, then updates the key to a new value and verifies that the value has been accurately updated.
+/// 3. `test_others`: A third test that doesn't modify the database state. It can run in parallel with the other tests.
+///
+/// In this example, `test_insert` and `test_update` need to run in sequence to work, but it doesn't matter which test runs first.
+/// We can leverage a semaphore with a single permit to address this challenge.
+///
+/// ```
+/// # struct Database;
+/// # impl Database {
+/// #     pub const fn setup()-> Database {
+/// #         Database
+/// #     }
+/// # }
+///   
+///    use tokio::sync::Semaphore;
+///
+///    // 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 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 if the value has been inserted correctly.
+///         assert_eq!(DB.get(key), value);
+///
+///         // Undo the insertation, make database status unchanged.
+///         DB.delete(key).await;
+///
+///         // Drop permit, make possible waiting test to run.
+///         drop(permit);
+///     }
+///
+///     #[tokio::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 if the value has been updated correctly.
+///         assert_eq!(DB.get(key).await, new_value);
+///         
+///         // Undo any modificattion.
+///         DB.delete(key).await;
+///
+///         // Drop permit, make possible waiting test to run.
+///         drop(permit);
+///    }
+///
+///     #[tokio::test]
+///     async fn test_others() {
+///         // this test 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