Repository: tokio-rs/tokio
File: tokio/src/sync/mpsc/bounded.rs (Rust)

Code before:
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(rx.capacity(), 4);
    ///
    ///     // Sending and receiving a value increases the capacity by one.
    ///     permit.send(());
    ///     rx.recv().await.unwrap();
    ///     assert_eq!(rx.capacity(), 5);
    /// }
    /// ```
    /// [`capacity`]: Receiver::capacity
    /// [`max_capacity`]: Receiver::max_capacity
    pub fn capacity(&self) -> usize {
        self.chan.semaphore().semaphore.available_permits()
    }

    /// Returns the maximum buffer capacity of the channel.
    ///
    /// The maximum capacity is the buffer capacity initially specified when calling
    /// [`channel`]. This is distinct from [`capacity`], which returns the *current*
    /// available buffer capacity: as messages are sent and received, the value
    /// returned by [`capacity`] will go up or down, whereas the value
    /// returned by [`max_capacity`] will remain constant.
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::sync::mpsc;
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let (tx, rx) = mpsc::channel::<()>(5);
    ///
    ///     // both max capacity and capacity are the same at first
    ///     assert_eq!(rx.max_capacity(), 5);
    ///     assert_eq!(rx.capacity(), 5);
    ///
    ///     // Making a reservation doesn't change the max capacity.
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(rx.max_capacity(), 5);
    ///     // but drops the capacity by one
    ///     assert_eq!(rx.capacity(), 4);
    /// }
    /// ```
    /// [`capacity`]: Receiver::capacity
    /// [`max_capacity`]: Receiver::max_capacity
    pub fn max_capacity(&self) -> usize {
        self.chan.semaphore().bound
    }

    /// Polls to receive the next message on this channel.
    ///

Review comment (suggestion):
Hmm, this is not actually equal to `max_capacity - len`. Generally, sending a message goes through this procedure:

1. Acquire a permit for the message.
2. Write the message into the channel's storage.
3. Make the message available to receivers.

With the `len` method, the length only changes in step 3, but with this method, the capacity already changes in step 1. If the user is using [`Permit`](https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Permit.html) to acquire permits before sending messages, then there may be a long amount of time between step 1 and step 2.

The documentation should clearly explain the difference.

Code after:
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(rx.capacity(), 4);
    ///     assert_eq!(rx.len(), 0);
    ///
    ///     // Sending and receiving a value increases the capacity by one.
    ///     permit.send(());
    ///     assert_eq!(rx.len(), 1);
    ///     rx.recv().await.unwrap();
    ///     assert_eq!(rx.capacity(), 5);
    ///
    ///     // Directly sending a message drops the capacity by one.
    ///     tx.send(()).await.unwrap();
    ///     assert_eq!(rx.capacity(), 4);
    ///     assert_eq!(rx.len(), 1);
    ///
    ///     // Receiving the message increases the capacity by one.
    ///     rx.recv().await.unwrap();
    ///     assert_eq!(rx.capacity(), 5);
    ///     assert_eq!(rx.len(), 0);
    /// }
    /// ```
    /// [`capacity`]: Receiver::capacity
    /// [`max_capacity`]: Receiver::max_capacity
    pub fn capacity(&self) -> usize {
        self.chan.semaphore().semaphore.available_permits()
    }

    /// Returns the maximum buffer capacity of the channel.
    ///
    /// The maximum capacity is the buffer capacity initially specified when calling
    /// [`channel`]. This is distinct from [`capacity`], which returns the *current*
    /// available buffer capacity: as messages are sent and received, the value
    /// returned by [`capacity`] will go up or down, whereas the value
    /// returned by [`max_capacity`] will remain constant.
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::sync::mpsc;
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let (tx, rx) = mpsc::channel::<()>(5);
    ///
    ///     // both max capacity and capacity are the same at first
    ///     assert_eq!(rx.max_capacity(), 5);
    ///     assert_eq!(rx.capacity(), 5);
    ///
    ///     // Making a reservation doesn't change the max capacity.
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(rx.max_capacity(), 5);