ReferenceQueue (Java SE 23 & JDK 23)
Description: declaration: module: java.base, package: java.lang.ref, class: ReferenceQueue
Keywords: java.lang.ref.ReferenceQueue class

# Class ReferenceQueue<T>

java.lang.Object
java.lang.ref.ReferenceQueue<T>

Type Parameters:
  `T` - the type of the reference object

public class ReferenceQueue<T> extends Object
Reference queues, to which registered reference objects are appended by the garbage collector after the appropriate reachability changes are detected.

Memory consistency effects: The enqueueing of a reference to a queue (by the garbage collector, or by a successful call to `Reference.enqueue()`) happens-before the reference is removed from the queue by `poll()` or `remove(long)`.

Since:
  1.2

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ReferenceQueue()`
  Constructs a new reference-object queue.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Reference<? extends T>`
  `poll()`
  Polls this queue to see if a reference object is available.
  `Reference<? extends T>`
  `remove()`
  Removes the next reference object in this queue, blocking until one becomes available.
  `Reference<? extends T>`
  `remove(long timeout)`
  Removes the next reference object in this queue, blocking until either one becomes available or the given timeout period expires.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ReferenceQueue

    public ReferenceQueue()
    Constructs a new reference-object queue.

- ## Method Details

  - ### poll

    public Reference<? extends T> poll()
    Polls this queue to see if a reference object is available. If one is available without further delay then it is removed from the queue and returned. Otherwise this method immediately returns `null`.
    Returns:
      A reference object, if one was immediately available, otherwise `null`
    See Also:
      - `Reference.enqueue()`

  - ### remove

    public Reference<? extends T> remove(long timeout) throws InterruptedException
    Removes the next reference object in this queue, blocking until either one becomes available or the given timeout period expires.

    This method does not offer real-time guarantees: It schedules the timeout as if by invoking the `Object.wait(long)` method.

    Parameters:
      `timeout` - If positive, block for up to `timeout` milliseconds while waiting for a reference to be added to this queue. If zero, block indefinitely.
    Returns:
      A reference object, if one was available within the specified timeout period, otherwise `null`
    Throws:
      `IllegalArgumentException` - If the value of the timeout argument is negative
      `InterruptedException` - If the timeout wait is interrupted
    See Also:
      - `Reference.enqueue()`

  - ### remove

    public Reference<? extends T> remove() throws InterruptedException
    Removes the next reference object in this queue, blocking until one becomes available.
    Returns:
      A reference object, blocking until one becomes available
    Throws:
      `InterruptedException` - If the wait is interrupted
    See Also:
      - `Reference.enqueue()`