util: add DelayQueue::deadline

[aliu]

Motivation

When implementing a cache with item expirations (example from mini-redis), it's not possible to use DelayQueue as a more efficient backing store for the expirations. The reason is, when inserting/removing/modifying a cache entry there needs to be a way to determine whether the "next expiring time" has changed as a result of the operation. Basically, you'd need an api similar to DelayQueue::peek but for the next deadline in the queue. However, currently DelayQueue does not expose such an api, so you are left with having to store an independent mapping of Keys to expiration Instants and keep it in sync with all operations on the DelayQueue. It would be nice to not have to maintain this bookkeeping when DelayQueue already knows this information.

Solution

Originally, my first thought was to simply make DelayQueue::next_deadline public. However looking closer at the internals, it doesn't consider deadlines in the expired queue. So a user who inserts an already expired item into the queue and calls next_deadline might be surprised when they get None back. This function is used a lot internally as well, so I thought it would be best to not modify its behavior.

Instead we could expose a deadline function that takes a Key and returns its expiration time. This way, we could still get the next deadline via delay_queue.peek().map(|key| delay_queue.deadline(&key)).

[Darksonn]

Thanks.