/*
 * 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 static java.util.Objects.requireNonNull;

import com.google.common.annotations.GwtIncompatible;
import com.google.common.annotations.J2ktIncompatible;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.internal.Finalizer;
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 org.jspecify.annotations.Nullable;

/**
 * A reference queue with an associated background thread that dequeues references and invokes
 * {@link FinalizableReference#finalizeReferent()} on them. Java 9+ users should prefer {@link
 * java.lang.ref.Cleaner Cleaner}; see example <a href="#cleaner">below</a>.
 *
 * <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
 * {@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:
 *
 * {@snippet :
 * public class MyServer implements Closeable {
 *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
 *   // You might also share this between several objects.
 *
 *   private static final Set<Reference<?>> 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(...);
 *     ServerSocket serverSocket = myServer.serverSocket;
 *     try {
 *       Reference<?> reference = new FinalizablePhantomReference<MyServer>(myServer, frq) {
 *         @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);
 *     } finally {
 *       Reference.reachabilityFence(myServer);
 *     }
 *     return myServer;
 *   }
 *
 *   @Override
 *   public void close() throws IOException {
 *     serverSocket.close();
 *   }
 * }
 * }
 *
 * <p id="cleaner">Here is how you might achieve the same thing using {@link java.lang.ref.Cleaner
 * Cleaner}, if you are using a Java version where that is available:
 *
 * {@snippet :
 * public class MyServer implements Closeable {
 *   private static final Cleaner cleaner = Cleaner.create();
 *   // You might also share this between several objects.
 *
 *   private final ServerSocket serverSocket;
 *   private final Cleaner.Cleanable cleanable;
 *
 *   public MyServer(...) {
 *     ...
 *     this.serverSocket = new ServerSocket(...);
 *     this.cleanable = cleaner.register(this, closeServerSocketRunnable(serverSocket));
 *     ...
 *   }
 *
 *   private static Runnable closeServerSocketRunnable(ServerSocket serverSocket) {
 *     return () -> {
 *       if (!serverSocket.isClosed()) {
 *         ...log a message about how nobody called close()...
 *         try {
 *           serverSocket.close();
 *         } catch (IOException e) {
 *           ...
 *         }
 *       }
 *     };
 *   }
 *
 *   @Override
 *   public void close() throws IOException {
 *     serverSocket.close();
 *     cleanable.clean();
 *   }
 * }
 * }
 *
 * <p>Some care is needed when using {@code Cleaner} to ensure that the callback passed to {@code
 * register} does not have a reference to the object (in this case, {@code MyServer}) that may be
 * garbage-collected. That's why we are careful to make a {@code Runnable} that does not have a
 * reference to any {@code MyServer} instance.
 *
 * @author Bob Lee
 * @since 2.0
 */
@J2ktIncompatible
@GwtIncompatible
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.
   *
   * NOTE: The tests for this behavior (FinalizableReferenceQueueClassLoaderUnloadingTest) fail
   * strangely when run in JDK 9. We are considering this a known issue. Please see
   * https://github.com/google/guava/issues/3086 for more information.
   */

  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 FinalizerStarter finalizerStarter;

  static {
    Class<?> finalizer = loadFinalizer(new SystemLoader(), new DecoupledLoader());
    finalizerStarter =
        finalizer != null
            ? new ReflectiveStarter(getStartFinalizer(finalizer))
            : new DirectStarter();
  }

  /** 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<>();
    frqRef = new PhantomReference<>(this, queue);
    boolean threadStarted = false;
    try {
      finalizerStarter.startFinalizer(FinalizableReference.class, queue, frqRef);
      threadStarted = true;
    } 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.
   */
  final 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 will load Finalizer.
   *
   * @return a {@link Class} for {@link Finalizer} or {@code null} if none of the loaders load it
   */
  private static @Nullable Class<?> loadFinalizer(FinalizerLoader... loaders) {
    for (FinalizerLoader loader : loaders) {
      Class<?> finalizer = loader.loadFinalizer();
      if (finalizer != null) {
        return finalizer;
      }
    }

    return null;
  }

  /** Loads Finalizer.class. */
  interface FinalizerLoader {

    /**
     * Returns a {@link Class} for {@link Finalizer} or {@code null} if this loader shouldn't or
     * can't load it.
     *
     * @throws SecurityException if we don't have the appropriate privileges
     */
    @Nullable 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 final 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 @Nullable Class<?> loadFinalizer() {
      if (disabled) {
        return null;
      }
      if (isAndroid()) {
        // We need not worry about class unloading under Android. Plus, this approach wouldn't work.
        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 Guava to your system class path.";

    @Override
    public @Nullable Class<?> loadFinalizer() {
      if (isAndroid()) {
        // We need not worry about class unloading under Android. Plus, this approach wouldn't work.
        return null;
      }
      /*
       * 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.
       */
      try (URLClassLoader 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. */
    final 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);
    }
  }

  private interface FinalizerStarter {
    void startFinalizer(
        Class<?> finalizableReferenceClass,
        ReferenceQueue<Object> queue,
        PhantomReference<Object> frqRef)
        throws Throwable;
  }

  private static final class ReflectiveStarter implements FinalizerStarter {
    final Method startFinalizer;

    ReflectiveStarter(Method startFinalizer) {
      this.startFinalizer = startFinalizer;
    }

    @Override
    public void startFinalizer(
        Class<?> finalizableReferenceClass,
        ReferenceQueue<Object> queue,
        PhantomReference<Object> frqRef)
        throws Throwable {
      startFinalizer.invoke(null, finalizableReferenceClass, queue, frqRef);
    }
  }

  private static final class DirectStarter implements FinalizerStarter {
    @Override
    public void startFinalizer(
        Class<?> finalizableReferenceClass,
        ReferenceQueue<Object> queue,
        PhantomReference<Object> frqRef) {
      Finalizer.startFinalizer(finalizableReferenceClass, queue, frqRef);
    }
  }

  /** 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);
    }
  }

  private static boolean isAndroid() {
    return requireNonNull(System.getProperty("java.runtime.name", "")).contains("Android");
  }
}