On Mon, 27 Feb 2023 20:09:12 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.
>
>> @Martin-Buchholz Martin, how would you like to proceed with your proposed
>> wording, would you prefer a suggested edit to this PR, do a separate PR, or
>> otherwise? /cc @AlanBateman (any recommendation, Alan? thinking )
>
> Talked me into it - I will dust off my github/skara skillz and make a new PR.
>
>
> I wonder if there's now a way to override javadoc for remove() without
> creating a new method body.
@Martin-Buchholz I guess `remove` could be overridden and just delegate to
`super`?
-------------
PR: https://git.openjdk.org/jdk/pull/12729
