モジュール 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)

参照オブジェクトための抽象基底クラスです。 このクラスは、すべての参照オブジェクトに対して共通のオペレーションを定義します。 参照オブジェクトはガベージ・コレクタと密接に連携して実装されるので、このクラスを直接サブクラス化することはできません。

シール済クラス階層グラフ:

導入されたバージョン:

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(T)

refersTo

public final boolean refersTo(T obj)

この参照オブジェクトの参照がobjかどうかをテストします。 参照オブジェクトがクリアされている場合、null objを使用するとtrueが返されます。

パラメータ:

obj - この参照オブジェクト参照と比較するオブジェクト

戻り値:

objがこの参照オブジェクトの参照である場合はtrue

導入されたバージョン:

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

関連項目:

• Cloneable

reachabilityFence

public static void reachabilityFence(Object ref)

指定された参照によって参照されるオブジェクトが「強く到達可能な」のままであることを保証します。このため、オブジェクトが到達不能になる可能性のあるプログラムの以前のアクションに関係なく、参照されるオブジェクトは、少なくともこのメソッドの呼出し後までガベージ・コレクションによって再利用できません。 このメソッドを起動しても、ガベージ・コレクションまたはファイナライズは開始されません。

このメソッドは、ガベージ・コレクションに関して「強い到達性」の順序を設定します。 プログラム内に暗黙的にしか存在しないリレーションを制御 -- ガベージ・コレクションをトリガーする到達可能性条件。 この方法は、synchronizedブロックまたはメソッドを使用したり、他の同期機能を使用できない、または必要な制御を提供しない、早期ファイナライズのまれな状況で使用するように設計されています。 このメソッドは、リクレイムが可視効果を持つ可能性がある場合にのみ適用されます。これは、正確性のための順序付け制御に依存する方法で実装されたファイナライザ(「Java言語仕様」の12.6の項を参照してください)を持つオブジェクトに対して可能です。

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の呼出しは、updateの呼出しの後、actionの呼出しがこのオブジェクトの最後の使用であったとしても、配列スロットが更新の前にObject.finalize()によってアウトされないようにするために、直感的に配置されません。 たとえば、ユーザー・プログラムの使用法に、このResourceへの他の参照を保持しないnew Resource().action();という形式があった場合、このようになります。 ここでオーバーキルすると、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