RFR: JDK-8297605 DelayQueue javadoc is confusing
Martin Buchholz
martin at openjdk.org
Thu Feb 23 21:23:11 UTC 2023
On Thu, 23 Feb 2023 15:36:48 GMT, Viktor Klang <duke 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.
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
More information about the core-libs-dev
mailing list