sync: document maximum number of permits (#2539)

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()

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;

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);
     }

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;