feat(mpsc): add len, capacity, and remaining methods to mpsc (h…

…awkw#71)

src/mpsc/async_impl.rs

@@ -257,6 +257,80 @@ feature! {
                 .core
                 .try_send(self.inner.slots.as_ref(), val, &self.inner.recycle)
         }
+
+        /// Returns the *total* capacity of the channel for this [`Sender`].
+        /// This includes both occupied and unoccupied entries.
+        ///
+        /// To determine the channel's remaining *unoccupied* capacity, use
+        /// [`remaining`] instead.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, _) = channel::<usize>(100);
+        /// assert_eq!(tx.capacity(), 100);
+        /// ```
+        ///
+        /// Even after sending several messages, the capacity remains
+        /// the same:
+        /// ```
+        /// # use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, rx) = channel::<usize>(100);
+        /// *tx.try_send_ref().unwrap() = 1;
+        /// *tx.try_send_ref().unwrap() = 2;
+        /// *tx.try_send_ref().unwrap() = 3;
+        ///
+        /// assert_eq!(tx.capacity(), 100);
+        /// ```
+        ///
+        /// [`remaining`]: Self::remaining
+        #[inline]
+        pub fn capacity(&self ) -> usize {
+            self.inner.core.core.capacity()
+        }
+
+        /// Returns the unoccupied capacity of the channel for this [`Sender`]
+        /// (i.e., how many additional elements can be sent before the channel
+        /// will be full).
+        ///
+        /// This is equivalent to subtracting the channel's [`len`] from its [`capacity`].
+        ///
+        /// [`len`]: Self::len
+        /// [`capacity`]: Self::capacity
+        pub fn remaining(&self) -> usize {
+            self.capacity() - self.len()
+        }
+
+        /// Returns the number of elements in the channel of this [`Sender`].
+        ///
+        /// To determine the channel's remaining *unoccupied* capacity, use
+        /// [`remaining`] instead.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, rx) = channel::<usize>(100);
+        /// assert_eq!(tx.len(), 0);
+        ///
+        /// *tx.try_send_ref().unwrap() = 1;
+        /// *tx.try_send_ref().unwrap() = 2;
+        /// *tx.try_send_ref().unwrap() = 3;
+        /// assert_eq!(tx.len(), 3);
+        ///
+        /// let _ = rx.try_recv_ref().unwrap();
+        /// assert_eq!(tx.len(), 2);
+        /// ```
+        ///
+        /// [`remaining`]: Self::remaining
+        #[inline]
+        pub fn len(&self) -> usize {
+            self.inner.core.core.len()
+        }
     }
 
     impl<T, R> Clone for Sender<T, R> {
@@ -581,6 +655,80 @@ feature! {
         pub fn is_closed(&self) -> bool {
             test_dbg!(self.inner.core.tx_count.load(Ordering::SeqCst)) <= 1
         }
+
+        /// Returns the *total* capacity of the channel for this [`Receiver`].
+        /// This includes both occupied and unoccupied entries.
+        ///
+        /// To determine the channel's remaining *unoccupied* capacity, use
+        /// [`remaining`] instead.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, rx) = channel::<usize>(100);
+        /// assert_eq!(rx.capacity(), 100);
+        /// ```
+        ///
+        /// Even after sending several messages, the capacity remains
+        /// the same:
+        /// ```
+        /// # use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, rx) = channel::<usize>(100);
+        /// *tx.try_send_ref().unwrap() = 1;
+        /// *tx.try_send_ref().unwrap() = 2;
+        /// *tx.try_send_ref().unwrap() = 3;
+        ///
+        /// assert_eq!(rx.capacity(), 100);
+        /// ```
+        ///
+        /// [`remaining`]: Self::remaining
+        #[inline]
+        pub fn capacity(&self ) -> usize {
+            self.inner.core.core.capacity()
+        }
+
+        /// Returns the unoccupied capacity of the channel for this [`Receiver`]
+        /// (i.e., how many additional elements can be sent before the channel
+        /// will be full).
+        ///
+        /// This is equivalent to subtracting the channel's [`len`] from its [`capacity`].
+        ///
+        /// [`len`]: Self::len
+        /// [`capacity`]: Self::capacity
+        pub fn remaining(&self) -> usize {
+            self.capacity() - self.len()
+        }
+
+        /// Returns the number of elements in the channel of this [`Receiver`].
+        ///
+        /// To determine the channel's remaining *unoccupied* capacity, use
+        /// [`remaining`] instead.
+        ///
+        /// # Examples
+        ///
+        /// ```
+        /// use thingbuf::mpsc::channel;
+        ///
+        /// let (tx, rx) = channel::<usize>(100);
+        /// assert_eq!(tx.len(), 0);
+        ///
+        /// *tx.try_send_ref().unwrap() = 1;
+        /// *tx.try_send_ref().unwrap() = 2;
+        /// *tx.try_send_ref().unwrap() = 3;
+        /// assert_eq!(tx.len(), 3);
+        ///
+        /// let _ = rx.try_recv_ref().unwrap();
+        /// assert_eq!(rx.len(), 2);
+        /// ```
+        ///
+        /// [`remaining`]: Self::remaining
+        #[inline]
+        pub fn len(&self) -> usize {
+            self.inner.core.core.len()
+        }
     }
 
     impl<T, R> Drop for Receiver<T, R> {