Expose Semaphore::MAX_PERMITS and document it

Resolves #5129

tokio/src/sync/batch_semaphore.rs

@@ -128,7 +128,7 @@ impl Semaphore {
     /// implementation used three bits, so we will continue to reserve them to
     /// avoid a breaking change if additional flags need to be added in the
     /// future.
-    pub(crate) const MAX_PERMITS: usize = std::usize::MAX >> 3;
+    pub const MAX_PERMITS: usize = std::usize::MAX >> 3;
     const CLOSED: usize = 1;
     // The least-significant bit in the number of permits is reserved to use
     // as a flag indicating that the semaphore has been closed. Consequently

tokio/src/sync/semaphore.rs

@@ -124,6 +124,8 @@ fn bounds() {
 
 impl Semaphore {
     /// Creates a new semaphore with the initial number of permits.
+    ///
+    /// Panics if `permits` exceeds [`Semaphore::MAX_PERMITS`].
     #[track_caller]
     pub fn new(permits: usize) -> Self {
         #[cfg(all(tokio_unstable, feature = "tracing"))]
@@ -186,7 +188,7 @@ 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.
+    /// The maximum number of permits is [`Semaphore::MAX_PERMITS`], and this function will panic if the limit is exceeded.
     pub fn add_permits(&self, n: usize) {
         self.ll_sem.release(n);
     }
@@ -680,3 +682,10 @@ impl Drop for OwnedSemaphorePermit {
         self.sem.add_permits(self.permits as usize);
     }
 }
+
+impl Semaphore {
+    /// The maximum number of permits which a semaphore can hold.
+    ///
+    /// Exceeding this limit typically results in a panic.
+    pub const MAX_PERMITS : usize = super::batch_semaphore::Semaphore::MAX_PERMITS;
+}