add decrease_permit

tokio/src/sync/batch_semaphore.rs

@@ -368,6 +368,27 @@ impl Semaphore {
         assert_eq!(rem, 0);
     }
 
+    /// try to decrease at most `n` permits of this semaphore.
+    /// If the number of "permits" is negative, returns the number of "permits" that were reduced.
+    /// TODO: Doesn't that conflict with other places looking at self.permits?
+    pub(crate) fn decrease_permit(&self, n: usize) -> usize {
+        let mut curr_bit;
+        loop {
+            curr_bit = self.permits.load(Acquire);
+            let curr = curr_bit >> Self::PERMIT_SHIFT;
+            let new = curr.saturating_sub(n);
+            match self.permits.compare_exchange(
+                curr_bit,
+                new << Self::PERMIT_SHIFT,
+                AcqRel,
+                Acquire,
+            ) {
+                Ok(_) => break,
+                Err(_) => continue,
+            };
+        }
+        std::cmp::min(curr_bit >> Self::PERMIT_SHIFT, n)
+    }
     fn poll_acquire(
         &self,
         cx: &mut Context<'_>,

tokio/src/sync/semaphore.rs

@@ -481,6 +481,11 @@ impl Semaphore {
         self.ll_sem.release(n);
     }
 
+    /// docs
+    pub fn decrease_permit(&self, n: usize) -> usize {
+        self.ll_sem.decrease_permit(n)
+    }
+
     /// Acquires a permit from the semaphore.
     ///
     /// If the semaphore has been closed, this returns an [`AcquireError`].