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