RFR: JDK-8297605 DelayQueue javadoc is confusing

[Viktor Klang]

On Thu, 23 Feb 2023 18:53:35 GMT, Martin Buchholz <martin at openjdk.org> wrote:

>> Clarifies the distinction between expiration of the head of DelayQueue and how it relates to `poll`, `take`, and `peek`. See discussion on https://bugs.openjdk.org/browse/JDK-8297605
>> 
>> @DougLea If possible, please weigh in on whether this is in line with your thoughts on the matter.
>
> src/java.base/share/classes/java/util/concurrent/DelayQueue.java line 54:
> 
>> 52:  * when its delay has expired.  The <em>head</em> of the queue is that
>> 53:  * {@code Delayed} element whose delay expired furthest in the
>> 54:  * past.  If no delay has expired there is no head and {@code poll}
> 
> I like introducing the concept of "expired head".
> Aren't we defining "expired head" here, not "head"?

@Martin-Buchholz I read the line before the removed line (The <em>head</em> of the queue is that {@code Delayed} element whose delay expired furthest in the past.) as defining that the head will be the thing with the "soonest" expiry, which is important if one is used to LIFO or FIFO. Any idea on how we could improve that sentence? 🤔

-------------

PR: https://git.openjdk.org/jdk/pull/12729