FinalizableReference
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; /** * Implemented by references that have code to run after garbage collection of their referents. * * 由一些reference实现,这些reference是具有可以在他们的referents被垃圾回收后执行的代码的referent * * @see FinalizableReferenceQueue * @author Bob Lee * @since 2.0 (imported from Google Collections Library) */ public interface FinalizableReference { /** * Invoked on a background thread after the referent has been garbage collected unless security * restrictions prevented starting a background thread, in which case this method is invoked when * new references are created. * * 当referent被回收后调用一个后台线程,除非安全策略阻止启动这个安全线程,此时这个方法会在一个新的reference创建后被调用 */ void finalizeReferent(); }
FinalizablePhantomReference
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; import java.lang.ref.PhantomReference; import java.lang.ref.ReferenceQueue; /** * Phantom reference with a {@code finalizeReferent()} method which a background thread invokes * after the garbage collector reclaims the referent. This is a simpler alternative to using a * {@link ReferenceQueue}. * * 一个有可以在垃圾收集器回收referent后被后台线程调用的finalizeReferent()方法的虚引用 * 这是一个对ReferenceQueue更简单的替代 * * <p>Unlike a normal phantom reference, this reference will be cleared automatically. * 不像一个普通的虚引用,这个引用会自动清理 * * @author Bob Lee * @since 2.0 (imported from Google Collections Library) */ public abstract class FinalizablePhantomReference<T> extends PhantomReference<T> implements FinalizableReference { /** * Constructs a new finalizable phantom reference. * * @param referent to phantom reference * @param queue that should finalize the referent */ protected FinalizablePhantomReference(T referent, FinalizableReferenceQueue queue) { super(referent, queue.queue); queue.cleanUp(); } }
FinalizableReferenceQueue
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; import com.google.common.annotations.VisibleForTesting; import java.io.FileNotFoundException; import java.io.IOException; import java.lang.ref.Reference; import java.lang.ref.ReferenceQueue; import java.lang.reflect.Method; import java.net.URL; import java.net.URLClassLoader; import java.util.logging.Level; import java.util.logging.Logger; /** * A reference queue with an associated background thread that dequeues references and invokes * {@link FinalizableReference#finalizeReferent()} on them. * * 一个和后台线程关联的引用队列,他可以将引用出队并调用他们的FinalizableReference#finalizeReferent()方法 * * <p>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 {@code * finalizeReferent()} on the remaining references. * * 保留一个强引用给这个对象知道所有的关联引用都被终结.加入这个对象过早地被垃圾回收,后台线程将不会再调用剩余引用的finalizeReferent() * * @author Bob Lee * @since 2.0 (imported from Google Collections Library) */ public class FinalizableReferenceQueue { /* * The Finalizer thread keeps a phantom reference to this object. When the client (for example, a * map built by MapMaker) no longer has a strong reference to this object, the garbage collector * will reclaim it and enqueue the phantom reference. The enqueued reference will trigger the * Finalizer to stop. * * Finalizer 线程持有这个对象的虚引用.当客户端(比如一个由MapMaker创建的Map)不再有这个对象的强引用时 * 垃圾收集器将会回收它并将他的虚引用入队.这个入队的虚引用将会触发Finalizer的终止 * * If this library is loaded in the system class loader, FinalizableReferenceQueue can load * Finalizer directly with no problems. * * 假如这个lib是由system class loader加载的,FinalizableReferenceQueue可以直接加载Finalizer * * If this library is loaded in an application class loader, it's important that Finalizer not * have a strong reference back to the class loader. Otherwise, you could have a graph like this: * * 假如这个lib是由application class loader加载的,很重要的一点是Finalizer不会持有这个class loader的强引用. * 另外,你可以有个图,如下: * * Finalizer Thread runs instance of -> Finalizer.class loaded by -> Application class loader * which loaded -> ReferenceMap.class which has a static -> FinalizableReferenceQueue instance * * Finalizer Thread 运行一个 -> Finalizer.class的实例这个Finalizer.class被 -> Application class loader 加载 -> * Application class loader 加载的 ReferenceMap.class, 这个ReferenceMap持有一个静态的 -> FinalizableReferenceQueue实例 * * Even if no other references to classes from the application class loader remain, the Finalizer * thread keeps an indirect strong reference to the queue in ReferenceMap, which keeps the * Finalizer running, and as a result, the application class loader can never be reclaimed. * * 即使没有别的从application class loader中来的class的引用留下,Finalizer thread 也会保持一个在ReferenceMap * 中的这个queue的间接强引用, 这样可以保持Finalizer持续运行, 结论就是application class loader永远不会被垃圾回收 * * This means that dynamically loaded web applications and OSGi bundles can't be unloaded. * * 这意味着动态加载的web应用和OSGi bundles不能被卸载 * * If the library is loaded in an application class loader, we try to break the cycle by loading * Finalizer in its own independent class loader: * * 假如这个lib是被 application class loader 加载的,我们试图通过在他自己独立的class loader里加载Finalizer * 来破坏这个循环 * * System class loader -> Application class loader -> ReferenceMap -> FinalizableReferenceQueue * -> etc. -> Decoupled class loader -> Finalizer * * Now, Finalizer no longer keeps an indirect strong reference to the static * FinalizableReferenceQueue field in ReferenceMap. The application class loader can be reclaimed * at which point the Finalizer thread will stop and its decoupled class loader can also be * reclaimed. * * 现在, Finalizer不在持有ReferenceMap中的static 属性FinalizableReferenceQueue的强引用了,application class loader * 可以在Finalizer线程停止的时候被回收,并且他的解耦的class loader也可以被回收 * * If any of this fails along the way, we fall back to loading Finalizer directly in the * application class loader. * * 假如这种方法失败了,我们会回到使用直接在application class loader加载Finalizer的方式 */ private static final Logger logger = Logger.getLogger(FinalizableReferenceQueue.class.getName()); private static final String FINALIZER_CLASS_NAME = "com.google.common.base.internal.Finalizer"; /** Reference to Finalizer.startFinalizer(). */ /** Finalizer.startFinalizer(). 方法的引用 */ private static final Method startFinalizer; static { // TODO 分别使用SystemLoader(), DecoupledLoader, DirectLoader()来加载Finalizer Class<?> finalizer = loadFinalizer( new SystemLoader(), new DecoupledLoader(), new DirectLoader()); startFinalizer = getStartFinalizer(finalizer); } /** * The actual reference queue that our background thread will poll. * * 后台线程Finalizer用来clean reference的queue */ final ReferenceQueue<Object> queue; /** * Whether or not the background thread started successfully. * * 标记后台线程是否启动成功 */ final boolean threadStarted; /** * Constructs a new queue. * * 构造方法 */ @SuppressWarnings("unchecked") public FinalizableReferenceQueue() { // We could start the finalizer lazily, but I'd rather it blow up early. // 我们会延迟启动finalizer, 但我宁愿他早点启动 ReferenceQueue<Object> queue; boolean threadStarted = false; try { // TODO 这里invoke(null)是怎么做到的 queue = (ReferenceQueue<Object>) startFinalizer.invoke(null, FinalizableReference.class, this); threadStarted = true; } catch (IllegalAccessException impossible) { throw new AssertionError(impossible); // startFinalizer() is public } catch (Throwable t) { logger.log(Level.INFO, "Failed to start reference finalizer thread." + " Reference cleanup will only occur when new references are created.", t); queue = new ReferenceQueue<Object>(); } this.queue = queue; this.threadStarted = threadStarted; } /** * Repeatedly dequeues references from the queue and invokes {@link * FinalizableReference#finalizeReferent()} on them until the queue is empty. This method is a * no-op if the background thread was created successfully. * * 当finalizer线程启动失败的时候,手动调用cleanUp()方法来清理queue里的reference */ void cleanUp() { if (threadStarted) { return; } Reference<?> reference; while ((reference = queue.poll()) != null) { /* * This is for the benefit of phantom references. Weak and soft references will have already * been cleared by this point. * * 这个清理的方法跟Finalizer里的cleanUp()是一样的 */ reference.clear(); try { ((FinalizableReference) reference).finalizeReferent(); } catch (Throwable t) { logger.log(Level.SEVERE, "Error cleaning up after reference.", t); } } } /** * Iterates through the given loaders until it finds one that can load Finalizer. * * 使用一组loader遍历加载finalizer直到加载成功 * * @return Finalizer.class */ private static Class<?> loadFinalizer(FinalizerLoader... loaders) { for (FinalizerLoader loader : loaders) { Class<?> finalizer = loader.loadFinalizer(); if (finalizer != null) { return finalizer; } } throw new AssertionError(); } /** * Loads Finalizer.class. * * 顶一个load Finalizer的加载器 */ interface FinalizerLoader { /** * Returns Finalizer.class or null if this loader shouldn't or can't load it. * * 加载成功返回Finalizer.class * * @throws SecurityException if we don't have the appropriate privileges */ Class<?> loadFinalizer(); } /** * Tries to load Finalizer from the system class loader. If Finalizer is in the system class path, * we needn't create a separate loader. * * 尝试使用system class loader来加载Finalizer * 假如Finalizer已经在system class path中,则不需要再创建一个分离的loader */ static class SystemLoader implements FinalizerLoader { // This is used by the ClassLoader-leak test in FinalizableReferenceQueueTest to disable // 这个变量用来给 FinalizableReferenceQueueTest 做 ClassLoader-leak 测试用 // finding Finalizer on the system class path even if it is there. // 在system class path中寻找Finalizer @VisibleForTesting // 标记这是一个测试变量的annotation static boolean disabled; @Override public Class<?> loadFinalizer() { if (disabled) { return null; } ClassLoader systemLoader; try { systemLoader = ClassLoader.getSystemClassLoader(); } catch (SecurityException e) { logger.info("Not allowed to access system class loader."); return null; } if (systemLoader != null) { try { return systemLoader.loadClass(FINALIZER_CLASS_NAME); } catch (ClassNotFoundException e) { // Ignore. Finalizer is simply in a child class loader. // Finalizer在child class loader的情况 return null; } } else { return null; } } } /** * Try to load Finalizer in its own class loader. If Finalizer's thread had a direct reference to * our class loader (which could be that of a dynamically loaded web application or OSGi bundle), * it would prevent our class loader from getting garbage collected. * * 尝试使用Finalizer自己的class loader来加载Finalizer, 假如Finalizer线程有一个对我们的class loader的直接引用 * (这可能是一个动态加载的web程序或者OSGi bundle) * 他将会阻止我们的class loader被垃圾回收 */ static class DecoupledLoader implements FinalizerLoader { private static final String LOADING_ERROR = "Could not load Finalizer in its own class loader." + "Loading Finalizer in the current class loader instead. As a result, you will not be able" + "to garbage collect this class loader. To support reclaiming this class loader, either" + "resolve the underlying issue, or move Google Collections to your system class path."; @Override public Class<?> loadFinalizer() { try { /* * We use URLClassLoader because it's the only concrete class loader implementation in the * JDK. If we used our own ClassLoader subclass, Finalizer would indirectly reference this * class loader: * * 我们使用 URLClassLoader因为它是JDK中唯一各一个class loader实现 * 假如我们使用自己的ClassLoader子类, Finalizer将会有一个间接引用到this class loader * * Finalizer.class -> CustomClassLoader -> CustomClassLoader.class -> This class loader * * System class loader will (and must) be the parent. * * System class loader 将会是(也必须是) 父 class loader */ ClassLoader finalizerLoader = newLoader(getBaseUrl()); return finalizerLoader.loadClass(FINALIZER_CLASS_NAME); } catch (Exception e) { logger.log(Level.WARNING, LOADING_ERROR, e); return null; } } /** * Gets URL for base of path containing Finalizer.class. * * 获取包含Finalizer.class的基础路径的URL */ URL getBaseUrl() throws IOException { // Find URL pointing to Finalizer.class file. // 找到Finalizer.class文件的URL String finalizerPath = FINALIZER_CLASS_NAME.replace('.', '/') + ".class"; URL finalizerUrl = getClass().getClassLoader().getResource(finalizerPath); if (finalizerUrl == null) { throw new FileNotFoundException(finalizerPath); } // Find URL pointing to base of class path. // 找到class path的base URL String urlString = finalizerUrl.toString(); if (!urlString.endsWith(finalizerPath)) { throw new IOException("Unsupported path style: " + urlString); } // 获取Finalizer.class的base路径字符串 urlString = urlString.substring(0, urlString.length() - finalizerPath.length()); // 返回一个以finalizerUrl为域名,base urlString为后缀的URL return new URL(finalizerUrl, urlString); } /** Creates a class loader with the given base URL as its classpath. */ /** 使用指定的URL创建一个class loader */ URLClassLoader newLoader(URL base) { // We use the bootstrap class loader as the parent because Finalizer by design uses // only standard Java classes. That also means that FinalizableReferenceQueueTest // doesn't pick up the wrong version of the Finalizer class. // 我们使用bootstrap class loader来作为父loader因为Finalizer的设计是使用标准java类设计的 // 也就是说FinalizableReferenceQueueTest无法找出错误的Finalizer class版本 return new URLClassLoader(new URL[] {base}, null); } } /** * Loads Finalizer directly using the current class loader. We won't be able to garbage collect * this class loader, but at least the world doesn't end. * * 使用当前Application Class Loader直接加载Finalizer,这样我们将不能呢对这个class loader进行垃圾回收 * 但至少这个世界不会毁灭... */ static class DirectLoader implements FinalizerLoader { @Override public Class<?> loadFinalizer() { try { return Class.forName(FINALIZER_CLASS_NAME); } catch (ClassNotFoundException e) { throw new AssertionError(e); } } } /** * Looks up Finalizer.startFinalizer(). * * 返回Finalizer的startFinalizer()方法 */ static Method getStartFinalizer(Class<?> finalizer) { try { return finalizer.getMethod("startFinalizer", Class.class, Object.class); } catch (NoSuchMethodException e) { throw new AssertionError(e); } } }