クラス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)
参照オブジェクトための抽象基底クラスです。 このクラスは、すべての参照オブジェクトに対して共通のオペレーションを定義します。 参照オブジェクトはガベージ・コレクタと密接に連携して実装されるので、このクラスを直接サブクラス化することはできません。
シール済クラス階層グラフ:
参照の密封クラス階層グラフ参照の密封クラス階層グラフ
導入されたバージョン:
1.2

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    clear()
    この参照オブジェクトをクリアします。
    protected Object
    clone()
    CloneNotSupportedExceptionをスローします。
    boolean
    enqueue()
    この参照オブジェクトをクリアし、登録されているキュー(ある場合)への追加を試みます。
    T
    get()
    参照オブジェクトのリファレントを返します。
    boolean
    isEnqueued()
    非推奨。
    このメソッドは当初、参照オブジェクトがクリアされてエンキューされたかどうかをテストするために指定されていましたが、このテストを行うために実装されたことはありません。
    static void
    reachabilityFence(Object ref)
    指定されたオブジェクトが「強く到達可能な」のままであることを確認します。
    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.get() == objではなくref.refersTo(obj)を使用します。
      戻り値:
      この参照が表すオブジェクト。この参照オブジェクトがクリアされている場合はnull
      関連項目:

    • refersTo

      public final boolean refersTo(T obj)
      この参照オブジェクトの参照がobjかどうかをテストします。 参照オブジェクトがクリアされている場合、null objを使用するとtrueが返されます。
      パラメータ:
      obj - この参照オブジェクト参照と比較するオブジェクト
      戻り値:
      objがこの参照オブジェクトの参照である場合はtrue
      導入されたバージョン:
      16

    • clear

      public void clear()
      この参照オブジェクトをクリアします。 このメソッドを起動しても、このオブジェクトはエンキューされず、ガベージ・コレクタはこのオブジェクトをクリアまたはエンキューしません。

      ガベージ・コレクタまたはenqueue()メソッドによって参照がクリアされると、このメソッドを呼び出さずに直接クリアされます。

      APIのノート:
      ガベージ・コレクタとの競合状態が発生する可能性があります。 このメソッドがコールされると、ガベージ・コレクタが、この参照のクリアまたはエンキュー(あるいはその両方)の(またはすでに完了)プロセスにすでに存在する可能性があります。 必要に応じてreachabilityFence(Object)を使用して、clear()のコール後まで参照に強く到達できるようにすることで、この競合を回避します。

    • isEnqueued

      @Deprecated(since="16") public boolean isEnqueued()
      非推奨。
      このメソッドは当初、参照オブジェクトがクリアされてエンキューされたかどうかをテストするために指定されていましたが、このテストを行うために実装されたことはありません。 このメソッドは、固有の競合状態または関連するReferenceQueueがないことが原因で、誤用される可能性があります。 このメソッドを使用してクリティカル・リソースを解放するアプリケーションは、重大なパフォーマンスの問題を引き起こす可能性があります。 アプリケーションでは、エンキューされた参照オブジェクトを確実に判別するためにReferenceQueueを使用するか、この参照オブジェクトがクリアされたかどうかを判断するためにrefersTo(null)を使用する必要があります。
      この参照オブジェクトが関連付けられたキュー内にあるかどうかをテストします(ある場合)。 このメソッドは、次の条件がすべて満たされている場合にのみtrueを戻します:
      • この参照オブジェクトは、作成時にキューに登録されています
      • ガベージ・コレクタがこの参照オブジェクトをキューに追加したか、enqueue()が呼び出された場合
      • この参照オブジェクトはまだキューから削除されていません。
      それ以外の場合、このメソッドはfalseを返します。 この参照オブジェクトがクリアされているが、競合状態のためにエンキューされていない場合、このメソッドはfalseを返すことがあります。
      戻り値:
      この参照オブジェクトが関連付けられたキュー(もしあれば)内にある場合にのみtrue。

    • enqueue

      public boolean enqueue()
      この参照オブジェクトをクリアし、登録されているキュー(ある場合)への追加を試みます。

      この参照がキューに登録されているが、まだエンキューされていない場合、参照はキューに追加されます。このメソッドは「幸運な」で、trueを返します。 この参照がキューに登録されていないか、すでに(ガベージ・コレクタ、またはenqueueへの以前のコールによって)がエンキューされている場合、このメソッドは「失敗」で、falseを返します。

      メモリーの一貫性の影響: enqueue happen-beforeへの幸運なコールの前にスレッド内のアクションでは、参照はReferenceQueue.poll()またはReferenceQueue.remove(long)によってキューから削除されます。 enqueueへの「失敗」コールには、メモリーの一貫性の影響は指定されていません。

      このメソッドが参照をクリアすると、clear()メソッドを呼び出さずに直接クリアされます。 ガベージ・コレクタが参照をクリアしてエンキューすると、clear()メソッドまたはこのメソッドを呼び出さずに、直接実行されます。

      APIのノート:
      このメソッドを使用すると、登録済キューのReferenceQueue.poll()メソッドおよびReferenceQueue.remove(long)メソッドは、参照が引き続き強く到達可能であっても、この参照を戻すことができます。
      戻り値:
      この参照オブジェクトがキューに入れられた場合はtrue。すでにキューに入れられているか、作成時にキューに登録されなかった場合はfalse

    • clone

      protected Object clone() throws CloneNotSupportedException
      CloneNotSupportedExceptionをスローします。 Referenceは、効果的にクローニングできません。 かわりに新規のReferenceを構築します。
      オーバーライド:
      clone、クラスObject
      戻り値:
      通常の戻り値はありません
      例外:
      CloneNotSupportedException - 常時
      導入されたバージョン:
      11
      関連項目:

    • reachabilityFence

      public static void reachabilityFence(Object ref)
      指定されたオブジェクトが「強く到達可能な」のままであることを確認します。 この到達可能性は、仮想マシンが実行する変換の最適化に関係なく保証されます。そうしないと、オブジェクトがアクセスできない(JLS 12.6.1を参照してください)になる可能性があります。 したがって、指定されたオブジェクトは、少なくともこのメソッドの起動後までガベージ・コレクションによって再利用できません。 指定したオブジェクトへの参照は、このメソッドの起動後までガベージ・コレクタによって(またはエンキュー済(該当する場合))がクリアされません。 このメソッドを起動しても、参照処理、ガベージ・コレクションまたはファイナライズは開始されません。

      このメソッドは、ガベージ・コレクションに関して「強い到達性」の順序を設定します。 プログラム内に暗黙的にしか存在しないリレーションを制御 -- ガベージ・コレクションをトリガーする到達可能性条件。 このメソッドは、ファイナライザまたはCleanerを使用するオブジェクト、または「参照処理」を実行するコードなど、再利用に目に見える効果がある場合にのみ適用できます。

      メモリーの一貫性の影響: reachabilityFence(x) happen-beforeをコールする前のスレッド内のアクションでは、ガベージ・コレクタはxへの参照をすべてクリアします。

      APIのノート:
      参照処理または最終決定は、オブジェクトが到達不能になった後に発生する可能性があります。 オブジェクト (ファイナライザの実行以外)が必要ないことを仮想マシンが検出すると、オブジェクトにアクセスできなくなる可能性があります。 最適化の過程で、仮想マシンはオブジェクトのメソッドの操作を並べ替えて、オブジェクトが予期されるよりも早く必要なくなるようにすることができます - オブジェクトのメソッドがまだ実行されている間も含みます。 たとえば、VMは、valuesのロードをオブジェクトのフィールドから先に実行するように移動できます。 オブジェクト自体は不要になり、アクセスできなくなり、取得した値を使用してメソッドの実行を続行できます。 クリーナまたはファイナライザをクリーンアップに使用すると、驚くほど好ましくない影響が生じる可能性があります: メソッドを実行するプログラム・スレッドと、Cleanerまたはfinalizerを実行するクリーンアップ・スレッドとの間に競合があります。 クリーンアップ・スレッドはリソースを解放し、その後にプログラム・スレッド(メソッドの実行中)が解放されたリソースへのアクセスを試行します。 reachabilityFenceを使用すると、オブジェクトが強く到達可能であることを確認することで、この競合を回避できます。

      次に、クラスに関連付けられた簿記が配列索引によって管理される例を示します。 ここで、メソッドactionはreachabilityFenceを使用して、関連するExternalResourceのブックキーピングが実行される前に、Resourceオブジェクトが再利用されないようにします。具体的には、ExternalResourceを保持する配列スロットがメソッドObject.finalize()で除外されないようにするためです。そうしないと、同時に実行される可能性があります。 

      class Resource {
  private static ExternalResource[] externalResourceArray = ...

  int myIndex;
  Resource(...) {
    this.myIndex = ...
    externalResourceArray[myIndex] = ...;
    ...
  }
  protected void finalize() {
    externalResourceArray[this.myIndex] = null;
    ...
  }
  public void action() {
    try {
      // ...
      int i = this.myIndex; // last use of 'this' Resource in action()
      Resource.update(externalResourceArray[i]);
    } finally {
      Reference.reachabilityFence(this);
    }
  }
  private static void update(ExternalResource ext) {
    ext.status = ...;
  }
}
      reachabilityFenceの呼出しは、updateの呼出しの後に配置され、actionの呼出しがこのオブジェクトの最後の使用であったとしても、配列スロットが更新の前にObject.finalize()によってヌル・アウトされないようにします。 たとえば、ユーザー・プログラムの使用法にnew Resource().action();という形式があり、このResourceへの他の参照が保持されていない場合などです。 reachabilityFenceコールはfinallyブロックに配置され、メソッド内のすべてのパスで確実に呼び出されます。 より複雑なメソッドでは、reachabilityFenceがすべてのコード・パスで検出されるように、さらに注意が必要な場合があります。

      メソッドreachabilityFenceは、それ自体が到達可能性を保証する構造では必要ありません。 たとえば、ロックされているオブジェクトは一般に再利用できないため、クラスResource (finalizeを含む)のすべてのメソッドで、オブジェクトのすべてのアクセスがsynchronized (this)ブロックで囲まれている場合は十分です。 (さらに、このようなブロックには無限ループを含めることも、それ自体が到達不能であることも、"一般に"免責条項に対するコーナー・ケースの例外に該当するものとします。) ただし、同期が効率的、望ましい、または可能でない場合(デッドロックが発生する場合など)は、メソッドreachabilityFenceの方が適しています。

      パラメータ:
      ref - 強く到達可能なオブジェクトへの参照。 nullの場合、このメソッドは効果がありません。
      導入されたバージョン:
      9