RFR: 8354111: JavaDoc states that Iterator.remove() is linear in the LinkedBlockingDeque

[kabutz]

On Tue, 8 Apr 2025 16:19:13 GMT, Chen Liang <liach at openjdk.org> wrote:

>> One of the features of the LinkedBlockingDeque is that it is a doubly-linked node queue, with pointers in each node to "prev" and "next", which allows remove() in the Iterator to remove the node in constant time. However, in the JavaDoc of the class, it lists Iterator.remove() as an example of a method that takes linear time.
>
> FYI @kabutz you can log in to bugs.openjdk.org and create an issue for your patch. This issue can be noreg-doc, but will require a small CSR (which you can create and write, as you are already an author) as this touches specification text, for archival purpose.

Hi @liach I found another mistake in the JavaDoc - it states "Linked nodes are dynamically created upon each insertion unless this would bring the deque above capacity." - however, in the LBD they do create the nodes even if we have reached capacity. This comment was copied over from LBQ, but is not strictly speaking correct for LBD. We could change the code to reflect the comment, or remove that sentence. Which way should we proceed?

> Hi @liach I found another mistake in the JavaDoc - it states "Linked nodes are dynamically created upon each insertion unless this would bring the deque above capacity." - however, in the LBD they do create the nodes even if we have reached capacity. This comment was copied over from LBQ, but is not strictly speaking correct for LBD. We could change the code to reflect the comment, or remove that sentence. Which way should we proceed?

Actually scratch that - I'll propose a fix that seems to improve other issues as well.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/24500#issuecomment-2787209541
PR Comment: https://git.openjdk.org/jdk/pull/24500#issuecomment-2787312914