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 }