RFR: 8052260: Reference.isEnqueued() spec does not match the long-standing behavior returning true iff it's in the ref queue [v3]

[Mandy Chung]

> `Reference::isEnqueued` method was never implemented as it was initially specified since 1.2. The specification says that it tests if this reference object has been enqueued, but the long-standing behavior is to test if this reference object is in its associated queue, only reflecting the state at the time when this method is executed. The implementation doesn't do what the specification promised, which might cause serious bugs if unnoticed. For example, an application that relies on this method to release critical resources could cause serious performance issues, in particular when this method is misused on Reference objects without an associated queue.  `Reference::refersTo(null)` is the better recommended way to test if a Reference object has been cleared.
> 
> This proposes to deprecate `Reference::isEnqueued`.  Also the spec is updated to match the long-standing behavior.
> 
> CSR: https://bugs.openjdk.java.net/browse/JDK-8189386

Mandy Chung has updated the pull request incrementally with one additional commit since the last revision:

  improve the deprecation message per feedback

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/1684/files
  - new: https://git.openjdk.java.net/jdk/pull/1684/files/b4f9b489..9acf8a56

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=1684&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=1684&range=01-02

  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/jdk/pull/1684.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/1684/head:pull/1684

PR: https://git.openjdk.java.net/jdk/pull/1684