tokio-util: time: add DelayQueue::peek

[Gelbpunkt]

Motivation

My goal is to implement an expiring LRU cache that uses a DashMap + DelayQueue with an optional maximum capacity. On capacity overflow, I want to remove the item that would've been next to expire. I described this issue in #5279.

Solution

Adding DelayQueue::peek allows for getting the Key that will expire next. In my usecase, a DelayQueue<K> + DashMap<K, V> is used, so after removing the next expiring key from the queue, it can also be used to remove it from the map because K is now known. I made an implementation that showcases this here.

This implementation is based on pop_entry_slot and uses peek methods instead which don't touch the contents of the stack and levels.

Closes: #5279

[Darksonn]

The test failure isn't your fault. See #5570.

[Darksonn]

However, there's a test failure now, which appears to be in your code.

[Gelbpunkt]

However, there's a test failure now, which appears to be in your code.

Not quite sure why, this code shouldn't behave differently on Windows. Do you have any idea why that might be? Worst case I can try increasing the durations used.

[Darksonn]

The proper fix would be to use time::pause().

[Gelbpunkt]

The proper fix would be to use time::pause().

I found the issue with the original test, the entry inserted at now was instantly marked expired and therefore the assumption didn't hold. Using now + ms(1) is guaranteed to be correct, even with a paused timer. Everything should be sorted now 🎉

[Darksonn]

So the behavior is different for timers that have already expired? Can you please elaborate on this in the documentation?

[Gelbpunkt]

So the behavior is different for timers that have already expired? Can you please elaborate on this in the documentation?

I've updated the documentation to reflect this

[Darksonn]

Honestly, the behavior for expired timers worries me a bit. It would be quite surprising if you don't closely read the docs. Can we not fix it?

[Gelbpunkt]

Honestly, the behavior for expired timers worries me a bit. It would be quite surprising if you don't closely read the docs. Can we not fix it?

Sure thing! I've restored the original test and it now considers entries marked as expired first.

[Darksonn]

Please add a test that it always returns the earliest key, even when there are multiple expired keys, no matter the order they were inserted in.

[Gelbpunkt]

Please add a test that it always returns the earliest key, even when there are multiple expired keys, no matter the order they were inserted in.

Added. nevermind, this is impossible with the current stack for expired entries. I'll clarify it in the documentation.

[Gelbpunkt]

I've renamed the method to peek as suggested on Discord and updated the documentation to mention that the order of entries is exactly as in poll_expired.

[Darksonn]

Thanks.