001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import com.google.common.annotations.GwtIncompatible;
018import com.google.common.annotations.VisibleForTesting;
019import java.io.Closeable;
020import java.io.FileNotFoundException;
021import java.io.IOException;
022import java.lang.ref.PhantomReference;
023import java.lang.ref.Reference;
024import java.lang.ref.ReferenceQueue;
025import java.lang.reflect.Method;
026import java.net.URL;
027import java.net.URLClassLoader;
028import java.util.logging.Level;
029import java.util.logging.Logger;
030import javax.annotation.CheckForNull;
031
032/**
033 * A reference queue with an associated background thread that dequeues references and invokes
034 * {@link FinalizableReference#finalizeReferent()} on them.
035 *
036 * <p>Keep a strong reference to this object until all of the associated referents have been
037 * finalized. If this object is garbage collected earlier, the backing thread will not invoke {@code
038 * finalizeReferent()} on the remaining references.
039 *
040 * <p>As an example of how this is used, imagine you have a class {@code MyServer} that creates a
041 * {@link java.net.ServerSocket ServerSocket}, and you would like to ensure that the {@code
042 * ServerSocket} is closed even if the {@code MyServer} object is garbage-collected without calling
043 * its {@code close} method. You <em>could</em> use a finalizer to accomplish this, but that has a
044 * number of well-known problems. Here is how you might use this class instead:
045 *
046 * <pre>{@code
047 * public class MyServer implements Closeable {
048 *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
049 *   // You might also share this between several objects.
050 *
051 *   private static final Set<Reference<?>> references = Sets.newConcurrentHashSet();
052 *   // This ensures that the FinalizablePhantomReference itself is not garbage-collected.
053 *
054 *   private final ServerSocket serverSocket;
055 *
056 *   private MyServer(...) {
057 *     ...
058 *     this.serverSocket = new ServerSocket(...);
059 *     ...
060 *   }
061 *
062 *   public static MyServer create(...) {
063 *     MyServer myServer = new MyServer(...);
064 *     final ServerSocket serverSocket = myServer.serverSocket;
065 *     Reference<?> reference = new FinalizablePhantomReference<MyServer>(myServer, frq) {
066 *       public void finalizeReferent() {
067 *         references.remove(this):
068 *         if (!serverSocket.isClosed()) {
069 *           ...log a message about how nobody called close()...
070 *           try {
071 *             serverSocket.close();
072 *           } catch (IOException e) {
073 *             ...
074 *           }
075 *         }
076 *       }
077 *     };
078 *     references.add(reference);
079 *     return myServer;
080 *   }
081 *
082 *   public void close() {
083 *     serverSocket.close();
084 *   }
085 * }
086 * }</pre>
087 *
088 * @author Bob Lee
089 * @since 2.0
090 */
091@GwtIncompatible
092@ElementTypesAreNonnullByDefault
093public class FinalizableReferenceQueue implements Closeable {
094  /*
095   * The Finalizer thread keeps a phantom reference to this object. When the client (for example, a
096   * map built by MapMaker) no longer has a strong reference to this object, the garbage collector
097   * will reclaim it and enqueue the phantom reference. The enqueued reference will trigger the
098   * Finalizer to stop.
099   *
100   * If this library is loaded in the system class loader, FinalizableReferenceQueue can load
101   * Finalizer directly with no problems.
102   *
103   * If this library is loaded in an application class loader, it's important that Finalizer not
104   * have a strong reference back to the class loader. Otherwise, you could have a graph like this:
105   *
106   * Finalizer Thread runs instance of -> Finalizer.class loaded by -> Application class loader
107   * which loaded -> ReferenceMap.class which has a static -> FinalizableReferenceQueue instance
108   *
109   * Even if no other references to classes from the application class loader remain, the Finalizer
110   * thread keeps an indirect strong reference to the queue in ReferenceMap, which keeps the
111   * Finalizer running, and as a result, the application class loader can never be reclaimed.
112   *
113   * This means that dynamically loaded web applications and OSGi bundles can't be unloaded.
114   *
115   * If the library is loaded in an application class loader, we try to break the cycle by loading
116   * Finalizer in its own independent class loader:
117   *
118   * System class loader -> Application class loader -> ReferenceMap -> FinalizableReferenceQueue ->
119   * etc. -> Decoupled class loader -> Finalizer
120   *
121   * Now, Finalizer no longer keeps an indirect strong reference to the static
122   * FinalizableReferenceQueue field in ReferenceMap. The application class loader can be reclaimed
123   * at which point the Finalizer thread will stop and its decoupled class loader can also be
124   * reclaimed.
125   *
126   * If any of this fails along the way, we fall back to loading Finalizer directly in the
127   * application class loader.
128   *
129   * NOTE: The tests for this behavior (FinalizableReferenceQueueClassLoaderUnloadingTest) fail
130   * strangely when run in JDK 9. We are considering this a known issue. Please see
131   * https://github.com/google/guava/issues/3086 for more information.
132   */
133
134  private static final Logger logger = Logger.getLogger(FinalizableReferenceQueue.class.getName());
135
136  private static final String FINALIZER_CLASS_NAME = "com.google.common.base.internal.Finalizer";
137
138  /** Reference to Finalizer.startFinalizer(). */
139  private static final Method startFinalizer;
140
141  static {
142    Class<?> finalizer =
143        loadFinalizer(new SystemLoader(), new DecoupledLoader(), new DirectLoader());
144    startFinalizer = getStartFinalizer(finalizer);
145  }
146
147  /** The actual reference queue that our background thread will poll. */
148  final ReferenceQueue<Object> queue;
149
150  final PhantomReference<Object> frqRef;
151
152  /** Whether or not the background thread started successfully. */
153  final boolean threadStarted;
154
155  /** Constructs a new queue. */
156  public FinalizableReferenceQueue() {
157    // We could start the finalizer lazily, but I'd rather it blow up early.
158    queue = new ReferenceQueue<>();
159    frqRef = new PhantomReference<>(this, queue);
160    boolean threadStarted = false;
161    try {
162      startFinalizer.invoke(null, FinalizableReference.class, queue, frqRef);
163      threadStarted = true;
164    } catch (IllegalAccessException impossible) {
165      throw new AssertionError(impossible); // startFinalizer() is public
166    } catch (Throwable t) {
167      logger.log(
168          Level.INFO,
169          "Failed to start reference finalizer thread."
170              + " Reference cleanup will only occur when new references are created.",
171          t);
172    }
173
174    this.threadStarted = threadStarted;
175  }
176
177  @Override
178  public void close() {
179    frqRef.enqueue();
180    cleanUp();
181  }
182
183  /**
184   * Repeatedly dequeues references from the queue and invokes {@link
185   * FinalizableReference#finalizeReferent()} on them until the queue is empty. This method is a
186   * no-op if the background thread was created successfully.
187   */
188  void cleanUp() {
189    if (threadStarted) {
190      return;
191    }
192
193    Reference<?> reference;
194    while ((reference = queue.poll()) != null) {
195      /*
196       * This is for the benefit of phantom references. Weak and soft references will have already
197       * been cleared by this point.
198       */
199      reference.clear();
200      try {
201        ((FinalizableReference) reference).finalizeReferent();
202      } catch (Throwable t) {
203        logger.log(Level.SEVERE, "Error cleaning up after reference.", t);
204      }
205    }
206  }
207
208  /**
209   * Iterates through the given loaders until it finds one that can load Finalizer.
210   *
211   * @return Finalizer.class
212   */
213  private static Class<?> loadFinalizer(FinalizerLoader... loaders) {
214    for (FinalizerLoader loader : loaders) {
215      Class<?> finalizer = loader.loadFinalizer();
216      if (finalizer != null) {
217        return finalizer;
218      }
219    }
220
221    throw new AssertionError();
222  }
223
224  /** Loads Finalizer.class. */
225  interface FinalizerLoader {
226
227    /**
228     * Returns Finalizer.class or null if this loader shouldn't or can't load it.
229     *
230     * @throws SecurityException if we don't have the appropriate privileges
231     */
232    @CheckForNull
233    Class<?> loadFinalizer();
234  }
235
236  /**
237   * Tries to load Finalizer from the system class loader. If Finalizer is in the system class path,
238   * we needn't create a separate loader.
239   */
240  static class SystemLoader implements FinalizerLoader {
241    // This is used by the ClassLoader-leak test in FinalizableReferenceQueueTest to disable
242    // finding Finalizer on the system class path even if it is there.
243    @VisibleForTesting static boolean disabled;
244
245    @Override
246    @CheckForNull
247    public Class<?> loadFinalizer() {
248      if (disabled) {
249        return null;
250      }
251      ClassLoader systemLoader;
252      try {
253        systemLoader = ClassLoader.getSystemClassLoader();
254      } catch (SecurityException e) {
255        logger.info("Not allowed to access system class loader.");
256        return null;
257      }
258      if (systemLoader != null) {
259        try {
260          return systemLoader.loadClass(FINALIZER_CLASS_NAME);
261        } catch (ClassNotFoundException e) {
262          // Ignore. Finalizer is simply in a child class loader.
263          return null;
264        }
265      } else {
266        return null;
267      }
268    }
269  }
270
271  /**
272   * Try to load Finalizer in its own class loader. If Finalizer's thread had a direct reference to
273   * our class loader (which could be that of a dynamically loaded web application or OSGi bundle),
274   * it would prevent our class loader from getting garbage collected.
275   */
276  static class DecoupledLoader implements FinalizerLoader {
277    private static final String LOADING_ERROR =
278        "Could not load Finalizer in its own class loader. Loading Finalizer in the current class "
279            + "loader instead. As a result, you will not be able to garbage collect this class "
280            + "loader. To support reclaiming this class loader, either resolve the underlying "
281            + "issue, or move Guava to your system class path.";
282
283    @Override
284    @CheckForNull
285    public Class<?> loadFinalizer() {
286      try {
287        /*
288         * We use URLClassLoader because it's the only concrete class loader implementation in the
289         * JDK. If we used our own ClassLoader subclass, Finalizer would indirectly reference this
290         * class loader:
291         *
292         * Finalizer.class -> CustomClassLoader -> CustomClassLoader.class -> This class loader
293         *
294         * System class loader will (and must) be the parent.
295         */
296        ClassLoader finalizerLoader = newLoader(getBaseUrl());
297        return finalizerLoader.loadClass(FINALIZER_CLASS_NAME);
298      } catch (Exception e) {
299        logger.log(Level.WARNING, LOADING_ERROR, e);
300        return null;
301      }
302    }
303
304    /** Gets URL for base of path containing Finalizer.class. */
305    URL getBaseUrl() throws IOException {
306      // Find URL pointing to Finalizer.class file.
307      String finalizerPath = FINALIZER_CLASS_NAME.replace('.', '/') + ".class";
308      URL finalizerUrl = getClass().getClassLoader().getResource(finalizerPath);
309      if (finalizerUrl == null) {
310        throw new FileNotFoundException(finalizerPath);
311      }
312
313      // Find URL pointing to base of class path.
314      String urlString = finalizerUrl.toString();
315      if (!urlString.endsWith(finalizerPath)) {
316        throw new IOException("Unsupported path style: " + urlString);
317      }
318      urlString = urlString.substring(0, urlString.length() - finalizerPath.length());
319      return new URL(finalizerUrl, urlString);
320    }
321
322    /** Creates a class loader with the given base URL as its classpath. */
323    URLClassLoader newLoader(URL base) {
324      // We use the bootstrap class loader as the parent because Finalizer by design uses
325      // only standard Java classes. That also means that FinalizableReferenceQueueTest
326      // doesn't pick up the wrong version of the Finalizer class.
327      return new URLClassLoader(new URL[] {base}, null);
328    }
329  }
330
331  /**
332   * Loads Finalizer directly using the current class loader. We won't be able to garbage collect
333   * this class loader, but at least the world doesn't end.
334   */
335  static class DirectLoader implements FinalizerLoader {
336    @Override
337    public Class<?> loadFinalizer() {
338      try {
339        return Class.forName(FINALIZER_CLASS_NAME);
340      } catch (ClassNotFoundException e) {
341        throw new AssertionError(e);
342      }
343    }
344  }
345
346  /** Looks up Finalizer.startFinalizer(). */
347  static Method getStartFinalizer(Class<?> finalizer) {
348    try {
349      return finalizer.getMethod(
350          "startFinalizer", Class.class, ReferenceQueue.class, PhantomReference.class);
351    } catch (NoSuchMethodException e) {
352      throw new AssertionError(e);
353    }
354  }
355}