On Thu, 23 Feb 2023 21:20:27 GMT, Martin Buchholz <mar...@openjdk.org> wrote:
> Here's my attempt:
>
> ```
> * An unbounded {@linkplain BlockingQueue blocking queue} of {@link Delayed}
> * elements, in which an element generally becomes eligible for removal when
> its
> * delay has expired.
> *
> * <p>An element is considered <em>expired</em> when its {@code
> * getDelay(TimeUnit.NANOSECONDS)} method would return a value less than or
> * equal to zero.
> *
> * <p>An element is considered the <em>head</em> of the queue if it is the
> * element with the earliest expiration time, whether in the past or the
> future,
> * if there is such an element.
> *
> * <p>An element is considered the <em>expired head</em> of the queue if it is
> * the <em>expired</em> element with the earliest expiration time in the
> * past, if there is such an element.
> * The <em>expired head</em>, when present, is also the <em>head</em>.
> *
> * <p>While this class implements the {@code BlockingQueue} interface, it
> * intentionally violates the general contract of {@code BlockingQueue}, in
> that
> * the following methods disregard the presence of unexpired elements and only
> * ever remove the <em>expired head</em>:
> *
> * <ul>
> * <li> {@link #poll()}
> * <li> {@link #poll(long,TimeUnit)}
> * <li> {@link #take()}
> * <li> {@link #remove()}
> * </ul>
> *
> * <p>All other methods operate on both expired and unexpired elements. For
> * example, the {@code size} method returns the count of all elements. Method
> * {@link peek()} may return the non-null <em>head</em> even when {@code
> * take()} would block waiting for that element to expire.
> *
> * <p>This queue does not permit null elements.
> ```
I think that approach sounds good. @DougLea, any opinion on this class javadoc
summary?
-------------
PR: https://git.openjdk.org/jdk/pull/12729
