On Thu, 23 Feb 2023 15:36:48 GMT, Viktor Klang <d...@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 an expired element. * * <p>This queue does not permit null elements. ------------- PR: https://git.openjdk.org/jdk/pull/12729
