On Thu, 23 Feb 2023 21:20:27 GMT, Martin Buchholz <mar...@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. > > 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? 🤔 ) ------------- PR: https://git.openjdk.org/jdk/pull/12729
