From a5c1a7de0399625792b476666ea1326cb8bcd75c Mon Sep 17 00:00:00 2001
From: ZSL <nova-me@whatsoo.org>
Date: Sat, 16 May 2020 18:41:45 +0800
Subject: [PATCH] sync: document maximum number of permits (#2539)

---
 tokio/src/lib.rs                  | 2 +-
 tokio/src/sync/batch_semaphore.rs | 4 +++-
 tokio/src/sync/semaphore.rs       | 2 ++
 tokio/src/sync/semaphore_ll.rs    | 3 ++-
 4 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
index fbfffcbfc..af7b8da4a 100644
--- a/tokio/src/lib.rs
+++ b/tokio/src/lib.rs
@@ -228,7 +228,7 @@
 //! on the number of blocking threads is very large. These limits can be
 //! configured on the [`Builder`].
 //!
-//! Two spawn a blocking task, you should use the [`spawn_blocking`] function.
+//! To spawn a blocking task, you should use the [`spawn_blocking`] function.
 //!
 //! [`Builder`]: crate::runtime::Builder
 //! [`spawn_blocking`]: crate::task::spawn_blocking()
diff --git a/tokio/src/sync/batch_semaphore.rs b/tokio/src/sync/batch_semaphore.rs
index f5bcc1b94..29f659a06 100644
--- a/tokio/src/sync/batch_semaphore.rs
+++ b/tokio/src/sync/batch_semaphore.rs
@@ -123,7 +123,9 @@ impl Semaphore {
         self.permits.load(Acquire) >> Self::PERMIT_SHIFT
     }
 
-    /// Adds `n` new permits to the semaphore.
+    /// Adds `added` new permits to the semaphore.
+    ///
+    /// The maximum number of permits is `usize::MAX >> 3`, and this function will panic if the limit is exceeded.
     pub(crate) fn release(&self, added: usize) {
         if added == 0 {
             return;
diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs
index 1bfeaebc9..2489d34aa 100644
--- a/tokio/src/sync/semaphore.rs
+++ b/tokio/src/sync/semaphore.rs
@@ -80,6 +80,8 @@ impl Semaphore {
     }
 
     /// Adds `n` new permits to the semaphore.
+    ///
+    /// The maximum number of permits is `usize::MAX >> 3`, and this function will panic if the limit is exceeded.
     pub fn add_permits(&self, n: usize) {
         self.ll_sem.release(n);
     }
diff --git a/tokio/src/sync/semaphore_ll.rs b/tokio/src/sync/semaphore_ll.rs
index ac4ae6faf..2b0049193 100644
--- a/tokio/src/sync/semaphore_ll.rs
+++ b/tokio/src/sync/semaphore_ll.rs
@@ -333,8 +333,9 @@ impl Semaphore {
 
         self.add_permits_locked(0, true);
     }
-
     /// Adds `n` new permits to the semaphore.
+    ///
+    /// The maximum number of permits is `usize::MAX >> 3`, and this function will panic if the limit is exceeded.
     pub(crate) fn add_permits(&self, n: usize) {
         if n == 0 {
             return;