模块 java.base
包 java.lang.ref

类 Reference<T>

java.lang.Object
java.lang.ref.Reference<T>
类型参数：
T - 对象的类型
已知子类：
PhantomReference , SoftReference , WeakReference
public abstract sealed class Reference<T> extends Object permits PhantomReference <T>, SoftReference <T>, WeakReference <T> (not exhaustive)
引用对象的抽象基类。此类定义所有引用对象共有的操作。因为引用对象是与垃圾收集器密切合作实现的，所以这个类可能不会被直接子类化。
密封类层次结构图：
Sealed class hierarchy graph for ReferenceSealed class hierarchy graph for Reference
自从：
1.2

  • 方法总结

    修饰符和类型
    方法
    描述
    void
    clear()
    清除此引用对象。
    protected Object
    clone()
    抛出 CloneNotSupportedException 。
    boolean
    enqueue()
    清除此引用对象并将其添加到它注册的队列（如果有）。
    T
    get()
    返回此引用对象的引用对象。
    boolean
    isEnqueued()
    已弃用。
    此方法最初指定用于测试引用对象是否已被清除并入队，但从未实现以进行此测试。
    static void
    reachabilityFence(Object ref)
    确保给定引用所引用的对象保持 strongly reachable ，而不管程序之前的任何操作是否可能导致对象变得无法访问；因此，被引用的对象至少在调用此方法之前不能被垃圾回收回收。
    final boolean
    refersTo(T obj)
    测试此引用对象的引用对象是否为 obj 。

    在类 java.lang.Object 中声明的方法

    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 方法详情

    • get

      public T  get()
      返回此引用对象的引用对象。如果此引用对象已被程序或垃圾收集器清除，则此方法返回 null 。
      API 注意：
      此方法返回对引用对象的强引用。这可能会导致垃圾收集器将其视为强可达，直到稍后的收集周期为止。 refersTo 方法可以在测试某个对象是否是引用对象的引用对象时避免这种强化；也就是说，使用 ref.refersTo(obj) 而不是 ref.get() == obj 。
      返回：
      此引用所指的对象，如果此引用对象已被清除，则为 null
      参见：

    • refersTo

      public final boolean refersTo(T  obj)
      测试此引用对象的引用对象是否为 obj 。如果引用对象已被清除，则使用 null obj 将返回 true。
      参数：
      obj - 与此引用对象的引用对象进行比较的对象
      返回：
      true 如果 obj 是这个引用对象的引用
      自从：
      16

    • clear

      public void clear()
      清除此引用对象。调用此方法不会导致此对象入队。

      此方法仅由 Java 代码调用；当垃圾收集器清除引用时，它会直接清除引用，而无需调用此方法。

    • isEnqueued

      @Deprecated (since ="16") public boolean isEnqueued()
      已弃用。
      此方法最初指定用于测试引用对象是否已被清除并入队，但从未实现以进行此测试。由于固有的竞争条件或没有关联的 ReferenceQueue ，此方法可能会被滥用。依赖此方法释放关键资源的应用程序可能会导致严重的性能问题。应用程序应使用 ReferenceQueue 来可靠地确定哪些引用对象已入队或使用 refersTo(null) 来确定此引用对象是否已被清除。
      测试此引用对象是否在其关联队列中（如果有）。仅当满足以下所有条件时，此方法才返回 true：
      • 此引用对象在创建时已注册到队列；和
      • 垃圾收集器已将此引用对象添加到队列中或调用了enqueue() ；和
      • 此引用对象尚未从队列中删除。
      否则，此方法返回 false 。如果此引用对象已被清除但由于竞争条件而未入队，则此方法可能返回 false。
      返回：
      true 当且仅当此引用对象在其关联队列中（如果有）。

    • enqueue

      public boolean enqueue()
      清除此引用对象并将其添加到它注册的队列（如果有）。

      此方法仅由 Java 代码调用；当垃圾收集器将引用排入队列时，它会直接这样做，而无需调用此方法。

      返回：
      true 如果此引用对象已成功入队； false 如果它已经入队或者在创建时没有在队列中注册

    • clone

      protected Object  clone() throws CloneNotSupportedException
      抛出 CloneNotSupportedException 。无法有意义地克隆 Reference。而是构建一个新的 Reference。
      重写：
      clone 在类 Object 中
      返回：
      永远不会正常返回
      抛出：
      CloneNotSupportedException - 总是
      自从：
      11
      参见：

    • reachabilityFence

      public static void reachabilityFence(Object  ref)
      确保给定引用所引用的对象保持 strongly reachable ，而不管程序之前的任何操作是否可能导致对象变得无法访问；因此，被引用的对象至少在调用此方法之前不能被垃圾回收回收。调用此方法本身不会启动垃圾收集或终结。

      此方法针对垃圾收集为 strong reachability 建立排序。它控制在其他情况下仅隐含在程序中的关系——触发垃圾收集的可达性条件。此方法设计用于过早终止的罕见情况，在这种情况下，无法使用 synchronized 块或方法，或无法使用其他同步设施或无法提供所需的控制。此方法仅适用于回收可能具有可见效果的情况，这对于具有终结器的对象是可能的（参见 Section 12.6 ofJava 语言规范) 以依赖于正确性的排序控制的方式实现。

      API 注意：
      每当虚拟机检测到没有对象的引用将存储在堆中时，可能会发生终结：垃圾收集器可能会回收该对象，即使该对象的字段仍在使用中，只要该对象否则变得无法访问.在以下示例中，与类关联的簿记通过数组索引管理的情况下，这可能会产生令人惊讶和不良的影响。在这里，action 方法使用reachabilityFence 来确保在对关联的ExternalResource 执行簿记之前不回收Resource 对象；特别是这里，以确保持有 ExternalResource 的数组插槽不会在方法 Object.finalize() 中被清零，否则可能会同时运行。 
       
 class Resource {
  private static ExternalResource[] externalResourceArray = ...

  int myIndex;
  Resource(...) {
   myIndex = ...
   externalResourceArray[myIndex] = ...;
   ...
  }
  protected void finalize() {
   externalResourceArray[myIndex] = null;
   ...
  }
  public void action() {
   try {
    // ...
    int i = myIndex;
    Resource.update(externalResourceArray[i]);
   } finally {
    Reference.reachabilityFence(this);
   }
  }
  private static void update(ExternalResource ext) {
   ext.status = ...;
  }
 }
      在这里，对 reachabilityFence 的调用非直观地放置在 after 对 update 的调用，以确保在更新之前数组槽不会被 Object.finalize() 清空，即使对 action 的调用是该对象的最后一次使用。例如，如果用户程序中的用法具有 new Resource().action(); 形式，其中不保留对此 Resource 的其他引用，则可能是这种情况。 reachabilityFence 被放置在 finally 块中，以确保它在方法中的所有路径中被调用，虽然在这里可能有点矫枉过正。在具有更复杂控制路径的方法中，您可能需要进一步的预防措施以确保在所有这些路径中遇到 reachabilityFence。

      有时可以更好地封装 reachabilityFence 的使用。继续上面的例子，如果对方法 update 的调用是可以接受的，即使终结器已经执行（清空槽），那么你可以本地化使用 reachabilityFence ：

       
 public void action2() {
  // ...
  Resource.update(getExternalResource());
 }
 private ExternalResource getExternalResource() {
  ExternalResource ext = externalResourceArray[myIndex];
  Reference.reachabilityFence(this);
  return ext;
 }

      在本身确保可达性的构造中不需要方法 reachabilityFence。例如，因为通常无法回收被锁定的对象，所以如果在 Resource 类（包括 finalize ）的所有方法中对对象的所有访问都包含在 synchronized (this) 块中就足够了。 （此外，此类块不得包含无限循环，或者它们本身不可访问，这属于“一般”免责声明的极端情况例外。）但是，在这种方法效率不高的情况下，方法 reachabilityFence 仍然是更好的选择，可取的，或可能的；例如因为它会遇到死锁。

      参数：
      ref - 参考。如果是 null ，则此方法无效。
      自从：
      9