Repository: tokio-rs/tokio
File: tokio-util/src/time/delay_queue.rs (Rust)

Code before:
    /// # async fn main() {
    /// let mut delay_queue = DelayQueue::with_capacity(10);
    ///
    /// let key1 = delay_queue.insert(5, Duration::from_secs(5));
    /// let key2 = delay_queue.insert(10, Duration::from_secs(10));
    /// let key3 = delay_queue.insert(15, Duration::from_secs(15));
    ///
    /// delay_queue.remove(&key2);
    ///
    /// delay_queue.compact();
    /// assert_eq!(delay_queue.capacity(), 2);
    /// # }
    /// ```
    pub fn compact(&mut self) {
        self.slab.compact();
    }

    /// Gets the [`Key`] that [`poll_expired`] will pull out of the queue next, without
    /// pulling it out or waiting for the deadline to expire.
    ///
    /// If entries are already expired at insertion, they are returned in order of
    /// insertion, not by how far in the past their deadline would have expired.
    ///
    /// The next expiring key is only recalculated when the queue is polled, therefore
    /// this method will potentially return already expired keys if the queue is not
    /// polled regularly.
    ///
    /// # Examples
    ///
    /// Basic usage
    ///
    /// ```rust
    /// use tokio_util::time::DelayQueue;
    /// use std::time::Duration;
    ///
    /// # #[tokio::main]
    /// # async fn main() {
    /// let mut delay_queue = DelayQueue::new();
    ///
    /// let key1 = delay_queue.insert("foo", Duration::from_secs(10));
    /// let key2 = delay_queue.insert("bar", Duration::from_secs(5));
    /// let key3 = delay_queue.insert("baz", Duration::from_secs(15));
    ///
    /// assert_eq!(delay_queue.peek().unwrap(), key2);
    /// # }
    /// ```
    ///
    /// [`Key`]: struct@Key
    /// [`poll_expired`]: method@Self::poll_expired
    pub fn peek(&self) -> Option<Key> {
        use self::wheel::Stack;

Review comment (suggestion):
Let's not promise insertion order here.
```suggestion
    /// Entries that have already expired may be returned in any order, but it is
    /// guaranteed that this method returns them in the same order as when items
    /// are popped from the `DelayQueue`.
```

Code after:
    /// # async fn main() {
    /// let mut delay_queue = DelayQueue::with_capacity(10);
    ///
    /// let key1 = delay_queue.insert(5, Duration::from_secs(5));
    /// let key2 = delay_queue.insert(10, Duration::from_secs(10));
    /// let key3 = delay_queue.insert(15, Duration::from_secs(15));
    ///
    /// delay_queue.remove(&key2);
    ///
    /// delay_queue.compact();
    /// assert_eq!(delay_queue.capacity(), 2);
    /// # }
    /// ```
    pub fn compact(&mut self) {
        self.slab.compact();
    }

    /// Gets the [`Key`] that [`poll_expired`] will pull out of the queue next, without
    /// pulling it out or waiting for the deadline to expire.
    ///
    /// Entries that have already expired may be returned in any order, but it is
    /// guaranteed that this method returns them in the same order as when items
    /// are popped from the `DelayQueue`.
    ///
    /// # Examples
    ///
    /// Basic usage
    ///
    /// ```rust
    /// use tokio_util::time::DelayQueue;
    /// use std::time::Duration;
    ///
    /// # #[tokio::main]
    /// # async fn main() {
    /// let mut delay_queue = DelayQueue::new();
    ///
    /// let key1 = delay_queue.insert("foo", Duration::from_secs(10));
    /// let key2 = delay_queue.insert("bar", Duration::from_secs(5));
    /// let key3 = delay_queue.insert("baz", Duration::from_secs(15));
    ///
    /// assert_eq!(delay_queue.peek().unwrap(), key2);
    /// # }
    /// ```
    ///
    /// [`Key`]: struct@Key
    /// [`poll_expired`]: method@Self::poll_expired
    pub fn peek(&self) -> Option<Key> {
        use self::wheel::Stack;

        self.expired.peek().or_else(|| self.wheel.peek())
    }