FinalizableReferenceQueue
Date: 2016-05-24

com.google.common.base

## Class FinalizableReferenceQueue

- java.lang.Object
- - com.google.common.base.FinalizableReferenceQueue

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class FinalizableReferenceQueue
      extends java.lang.Object
      implements java.io.Closeable

  A reference queue with an associated background thread that dequeues references and invokes `FinalizableReference.finalizeReferent()` on them.

  Keep a strong reference to this object until all of the associated referents have been finalized. If this object is garbage collected earlier, the backing thread will not invoke `finalizeReferent()` on the remaining references.

  As an example of how this is used, imagine you have a class `MyServer` that creates a a `ServerSocket`, and you would like to ensure that the `ServerSocket` is closed even if the `MyServer` object is garbage-collected without calling its `close` method. You could use a finalizer to accomplish this, but that has a number of well-known problems. Here is how you might use this class instead:

       public class MyServer implements Closeable {
         private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
         // You might also share this between several objects.

         private static final Set<Reference<?>> references = Sets.newConcurrentHashSet();
         // This ensures that the FinalizablePhantomReference itself is not garbage-collected.

         private final ServerSocket serverSocket;

         private MyServer(...) {
           ...
           this.serverSocket = new ServerSocket(...);
           ...
         }

         public static MyServer create(...) {
           MyServer myServer = new MyServer(...);
           final ServerSocket serverSocket = myServer.serverSocket;
           Reference<?> reference = new FinalizablePhantomReference<MyServer>(myServer, frq) {
             @Override public void finalizeReferent() {
               references.remove(this):
               if (!serverSocket.isClosed()) {
                 ...log a message about how nobody called close()...
                 try {
                   serverSocket.close();
                 } catch (IOException e) {
                   ...
                 }
               }
             }
           };
           references.add(reference);
           return myServer;
         }

         @Override public void close() {
           serverSocket.close();
         }
       }

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FinalizableReferenceQueue()` Constructs a new queue.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### FinalizableReferenceQueue

          public FinalizableReferenceQueue()

      Constructs a new queue.

  - ### Method Detail

    - #### close

          public void close()

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`