/*
 * 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.io.Closeable;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.lang.ref.PhantomReference;
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;

import com.google.common.annotations.VisibleForTesting;

/**
 * A reference queue with an associated background thread that dequeues
 * references and invokes {@link FinalizableReference#finalizeReferent()} on
 * them.
 *
 * <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.
 *
 * <p>
 * As an example of how this is used, imagine you have a class {@code MyServer}
 * that creates a a {@link java.net.ServerSocket ServerSocket}, and you would
 * like to ensure that the {@code ServerSocket} is closed even if the
 * {@code MyServer} object is garbage-collected without calling its
 * {@code close} method. You <em>could</em> use a finalizer to accomplish this,
 * but that has a number of well-known problems. Here is how you might use this
 * class instead:
 *
 * <pre>
 * public class MyServer implements Closeable {
 *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
 *   // You might also share this between several objects.
 *
 *   private static final Set&lt;Reference&lt;?>> 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&lt;?> reference = new FinalizablePhantomReference&lt;MyServer>(myServer, frq) {
 *       &#64;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;
 *   }
 *
 *   &#64;Override public void close() {
 *     serverSocket.close();
 *   }
 * }
 * </pre>
 *
 * @author Bob Lee
 * @since 2.0 (imported from Google Collections Library)
 */
public class FinalizableReferenceQueue implements Closeable {
	/*
	 * 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.
	 *
	 * If this library is loaded in the system class loader,
	 * FinalizableReferenceQueue can load Finalizer directly with no problems.
	 *
	 * 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:
	 *
	 * Finalizer Thread runs instance of -> Finalizer.class loaded by -> Application
	 * class loader which loaded -> ReferenceMap.class which has a static ->
	 * FinalizableReferenceQueue instance
	 *
	 * 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.
	 *
	 * This means that dynamically loaded web applications and OSGi bundles can't be
	 * unloaded.
	 *
	 * 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:
	 *
	 * 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.
	 *
	 * If any of this fails along the way, we fall back to loading Finalizer
	 * directly in the application class loader.
	 */

	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(). */
	private static final Method startFinalizer;
	static {
		Class<?> finalizer = loadFinalizer(new SystemLoader(), new DecoupledLoader(), new DirectLoader());
		startFinalizer = getStartFinalizer(finalizer);
	}

	/**
	 * The actual reference queue that our background thread will poll.
	 */
	final ReferenceQueue<Object> queue;

	final PhantomReference<Object> frqRef;

	/**
	 * Whether or not the background thread started successfully.
	 */
	final boolean threadStarted;

	/**
	 * Constructs a new queue.
	 */
	public FinalizableReferenceQueue() {
		// We could start the finalizer lazily, but I'd rather it blow up early.
		queue = new ReferenceQueue<Object>();
		frqRef = new PhantomReference<Object>(this, queue);
		boolean threadStarted = false;
		try {
			startFinalizer.invoke(null, FinalizableReference.class, queue, frqRef);
			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);
		}

		this.threadStarted = threadStarted;
	}

	@Override
	public void close() {
		frqRef.enqueue();
		cleanUp();
	}

	/**
	 * 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.
	 */
	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.
			 */
			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.
	 *
	 * @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.
	 */
	interface FinalizerLoader {

		/**
		 * Returns Finalizer.class or null if this loader shouldn't or can't load it.
		 *
		 * @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.
	 */
	static class SystemLoader implements FinalizerLoader {
		// This is used by the ClassLoader-leak test in FinalizableReferenceQueueTest to
		// disable
		// finding Finalizer on the system class path even if it is there.
		@VisibleForTesting
		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.
					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.
	 */
	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:
				 *
				 * Finalizer.class -> CustomClassLoader -> CustomClassLoader.class -> This class
				 * loader
				 *
				 * System class loader will (and must) be the parent.
				 */
				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.
		 */
		URL getBaseUrl() throws IOException {
			// Find URL pointing to Finalizer.class file.
			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.
			String urlString = finalizerUrl.toString();
			if (!urlString.endsWith(finalizerPath)) {
				throw new IOException("Unsupported path style: " + urlString);
			}
			urlString = urlString.substring(0, urlString.length() - finalizerPath.length());
			return new URL(finalizerUrl, urlString);
		}

		/** Creates a class loader with the given base URL as its classpath. */
		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.
			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.
	 */
	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().
	 */
	static Method getStartFinalizer(Class<?> finalizer) {
		try {
			return finalizer.getMethod("startFinalizer", Class.class, ReferenceQueue.class, PhantomReference.class);
		} catch (NoSuchMethodException e) {
			throw new AssertionError(e);
		}
	}
}