VarHandle クラス

定義

[Android.Runtime.Register("java/lang/invoke/VarHandle", ApiSince=33, DoNotGenerateAcw=true)]
public abstract class VarHandle : Java.Lang.Object

[<Android.Runtime.Register("java/lang/invoke/VarHandle", ApiSince=33, DoNotGenerateAcw=true)>]
type VarHandle = class
    inherit Object

継承

Object

JavaObject

Object

VarHandle

属性

RegisterAttribute

注釈

VarHandle は、静的フィールド、非静的フィールド、配列要素、またはオフヒープ データ構造のコンポーネントを含む、変数、またはパラメーターで定義された変数ファミリへの動的に厳密に型指定された参照です。 このような変数へのアクセスは、プレーンな読み取り/書き込みアクセス、揮発性の読み取り/書き込みアクセス、比較と設定など、さまざまな <em>アクセス モード</em>でサポートされています。

VarHandles は不変であり、表示状態がありません。 VarHandles をユーザーがサブクラス化することはできません。

VarHandle には、 <ul><li>a #varType variable type T、この VarHandle によって参照されるすべての変数の型、および <li>a #coordinateTypes coordinate typesCT1, CT2, ..., CTnのリスト、 <em>coordinate 式の型</em> この VarHandle によって参照される変数を共同で検索します。 </ul> 変数型と座標型はプリミティブ型または参照型であり、 Class オブジェクトによって表されます。 座標型の一覧が空の場合があります。

VarHandle インスタンスを生成または java.lang.invoke.MethodHandles.Lookup lookup ファクトリ メソッドは、サポートされている変数型と座標型のリストを文書化します。

各アクセス モードは、アクセス モードに名前付けされたシグネチャポリモーフィック メソッドである 1 つの <em>access mode メソッド</em> に関連付けられます。 VarHandle インスタンスでアクセス モード メソッドが呼び出されると、呼び出しの最初の引数は、変数がアクセスされるオブジェクトを正確に示す座標式です。 呼び出しの末尾の引数は、アクセス モードにとって重要な値を表します。 たとえば、さまざまな比較/設定または比較/交換アクセス モードでは、変数の期待値と新しい値に 2 つの末尾引数が必要です。

アクセス モード メソッドの呼び出しに対する引数のアリティと型は静的にチェックされません。 代わりに、各アクセス モード メソッドは、引数が動的にチェックされるメソッド シグネチャの一種として機能する、#accessModeType(AccessMode) access mode typeのインスタンスとして表されるMethodTypeを指定します。 アクセス モード型は、VarHandle インスタンスの座標型とアクセス モードの重要度の値の型に関して仮パラメーター型を提供します。 アクセス モード型では、多くの場合、VarHandle インスタンスの変数型の観点から戻り値の型も提供されます。 VarHandle インスタンスでアクセス モード メソッドを呼び出す場合、呼び出しサイトのシンボリック型記述子、呼び出しに対する引数の実行時の型、および戻り値の実行時の型は、アクセス モードの種類で指定された型と一致する必要があります。 一致が失敗すると、ランタイム例外がスローされます。

たとえば、アクセス モードメソッド #compareAndSet は、受信側が座標型が CT1, ..., CTn で変数型が Tの VarHandle インスタンスの場合、そのアクセス モードの種類が (CT1 c1, ..., CTn cn, T expectedValue, T newValue)booleanされることを指定します。 VarHandle インスタンスが配列要素にアクセスでき、その座標型がString[]され、変数型がintされている間にStringされているとします。 この VarHandle インスタンスの compareAndSet のアクセス モードの種類は (String[] c1, int c2, String expectedValue, String newValue)boolean。 このような VarHandle インスタンスは、 MethodHandles#arrayElementVarHandle(Class) array factory method によって生成され、配列要素に次のようにアクセスできます。

{@code
            String[] sa = ...
            VarHandle avh = MethodHandles.arrayElementVarHandle(String[].class);
            boolean r = avh.compareAndSet(sa, 10, "expected", "new");
            }

アクセス モードは、アトミック性と整合性のプロパティを制御します。 <em>Plain</em> 読み取り (get) および書き込み (set) アクセスは、参照と最大 32 ビットのプリミティブ値に対してのみビットごとのアトミックであることが保証され、実行中のスレッド以外のスレッドに対して監視可能な順序制約は適用されません。 <em>Opaque</em> 演算は、同じ変数へのアクセスに関してビットごとのアトミックで一貫性のある順序付けです。 不透明なプロパティに従うだけでなく、 <em>Acquire</em> モードの読み取りと後続のアクセスは、 <em>Release</em> モードの書き込みと以前のアクセスに一致した後に並べ替えられます。 Acquire プロパティと Release プロパティに従うことに加えて、すべての <em>Volatile</em> 操作は、お互いに対して完全に順序付けられます。

アクセス モードは、 <ul><li>指定されたメモリ順序付け効果で変数の値を取得する読み取りアクセス モードのカテゴリにグループ化されます。 このグループに属する対応するアクセス モード メソッドのセットは、 #get get、 #getVolatile getVolatile、 #getAcquire getAcquire、 #getOpaque getOpaqueのメソッドで構成されます。 <li>指定されたメモリ順序付け効果で変数の値を設定するアクセス モードを書き込みます。 このグループに属する対応するアクセス モード メソッドのセットは、 #set set、 #setVolatile setVolatile、 #setRelease setRelease、 #setOpaque setOpaqueのメソッドで構成されます。 <li>atomic 更新アクセス モード。たとえば、指定されたメモリ順序付け効果で変数の値をアトミックに比較して設定します。 このグループに属する対応するアクセス モードメソッドのセットは、 #compareAndSet compareAndSet、 #weakCompareAndSetPlain weakCompareAndSetPlain、 #weakCompareAndSet weakCompareAndSet、 #weakCompareAndSetAcquire weakCompareAndSetAcquire、 #weakCompareAndSetRelease weakCompareAndSetRelease、 #compareAndExchangeAcquire compareAndExchangeAcquire、 #compareAndExchange compareAndExchange、 #compareAndExchangeRelease compareAndExchangeRelease、 #getAndSet getAndSet、 #getAndSetAcquire getAndSetAcquire、 #getAndSetRelease getAndSetReleaseのメソッドで構成されます。 <li>アトミック更新アクセス モード。たとえば、指定されたメモリ順序付け効果の下で変数の値をアトミックに取得して設定します。 このグループに属する対応するアクセス モード メソッドのセットは、 #getAndAdd getAndAdd、 #getAndAddAcquire getAndAddAcquire、 #getAndAddRelease getAndAddRelease、 <li>ビットごとのアトミック更新アクセス モードで構成されます。たとえば、アトミックに取得し、ビットごとのアクセス モードを使用したり、指定されたメモリ順序付け効果で変数の値をビット単位で取得したりします。 このグループに属する対応するアクセス モードメソッドのセットは、 #getAndBitwiseOr getAndBitwiseOr、 #getAndBitwiseOrAcquire getAndBitwiseOrAcquire、 #getAndBitwiseOrRelease getAndBitwiseOrRelease、 #getAndBitwiseAnd getAndBitwiseAnd、 #getAndBitwiseAndAcquire getAndBitwiseAndAcquire、 #getAndBitwiseAndRelease getAndBitwiseAndRelease、 #getAndBitwiseXor getAndBitwiseXor、 #getAndBitwiseXorAcquire getAndBitwiseXorAcquire、 #getAndBitwiseXorRelease getAndBitwiseXorReleaseのメソッドで構成されます。 </ul>

VarHandle インスタンスを生成または java.lang.invoke.MethodHandles.Lookup lookup ファクトリ メソッドは、サポートされているアクセス モードのセットを文書化します。これには、変数の型と変数が読み取り専用かどうかに基づく制限の文書化も含まれる場合があります。 アクセス モードがサポートされていない場合、対応するアクセス モード メソッドは呼び出し時に UnsupportedOperationExceptionをスローします。 ファクトリ メソッドでは、アクセス モード メソッドによってスローされる可能性がある、宣言されていない例外を追加で文書化する必要があります。 #get get アクセス モードはすべての VarHandle インスタンスでサポートされており、対応するメソッドはUnsupportedOperationExceptionをスローしません。 VarHandle が読み取り専用変数 ( final フィールドなど) を参照している場合、書き込み、アトミック更新、数値アトミック更新、ビットごとのアトミック更新アクセス モードはサポートされず、対応するメソッドは UnsupportedOperationExceptionをスローします。 読み取り/書き込みアクセス モード (サポートされている場合) は、 get と setを除き、参照型とすべてのプリミティブ型にアトミック アクセスを提供します。 ファクトリ メソッドのドキュメントで特に明記されていない限り、アクセス モード get と set (サポートされている場合) は、32 ビット プラットフォームでの long と double を除き、参照型とすべてのプリミティブ型にアトミック アクセスを提供します。

アクセス モードは、変数の宣言サイトで指定されたメモリ順序付け効果をオーバーライドします。 たとえば、get アクセス モードを使用してフィールドにアクセスする VarHandle は、そのフィールドが<宣言されている場合でも>アクセス モード</em>emvolatile指定されたフィールドにアクセスします。 Java メモリ モデルでは驚くべき結果が得られる可能性があるため、混合アクセスを実行する場合は細心の注意を払う必要があります。

さまざまなアクセス モードでの変数へのアクセスをサポートするだけでなく、メモリの順序をきめ細かく制御するために、メモリ フェンス メソッドと呼ばれる静的メソッドのセットも提供されます。

Java言語仕様では、他のスレッドは、ロック、volatile フィールド、VarHandles の使用などの制約に従って、プログラムのソース コードで明らかな順序とは異なる順序で実行されたかのように操作を観察できます。 静的メソッド ( #fullFence fullFence、 #acquireFence acquireFence、 #releaseFence releaseFence、 #loadLoadFence loadLoadFence 、 #storeStoreFence storeStoreFence) を使用して制約を適用することもできます。 これらの仕様は、特定のアクセス モードの場合と同様に、"並べ替え" の欠如という点で表現されます。つまり、フェンスが存在しなかった場合に発生する可能性がある、観察可能な順序付け効果です。 アクセス モードメソッドとメモリフェンスメソッドの仕様のより正確な言い回しは、Java言語仕様の将来の更新に伴う可能性があります。

<h1>アクセス モード メソッドの呼び出しのコンパイル</h1>アクセス モード メソッドに名前を付けるJava メソッド呼び出し式は、ソース コードから VarHandle Java呼び出すことができます。 ソース コードの観点から、これらのメソッドは任意の引数を受け取ることができ、その多形の結果 (表現されている場合) は任意の戻り値の型にキャストできます。 正式には、これはアクセスモードメソッドに可変アリティ Object 引数と Object 戻り値の型を与えることによって実現されますが(戻り値の型がポリモーフィックの場合)、 <em>signatureポリモーフィズム</em> と呼ばれる追加の品質がありこの呼び出しの自由を JVM 実行スタックに直接接続します。

仮想メソッドの場合と同様に、アクセス モード メソッドのソース レベルの呼び出しは、 invokevirtual 命令にコンパイルされます。 さらに異常に、コンパイラは実際の引数の型を記録する必要があり、引数に対してメソッド呼び出し変換を実行しない可能性があります。 代わりに、独自の変換されていない型に従ってスタックにプッシュする命令を生成する必要があります。 VarHandle オブジェクト自体は、引数の前にスタックにプッシュされます。 コンパイラは、引数と戻り値の型を記述するシンボリック型記述子を使用してアクセス モード メソッドを呼び出す invokevirtual 命令を生成します。

完全なシンボリック型記述子を発行するには、コンパイラも戻り値の型を決定する必要があります (ポリモーフィックの場合)。 これは、メソッド呼び出し式が存在する場合はキャストに基づき、呼び出しが式の場合は Object 、呼び出しがステートメントの場合は void されます。 キャストはプリミティブ型 (ただし、 voidではない) にできます。

コーナー ケースとして、キャストされていない null 引数には、 java.lang.Voidのシンボリック型記述子が指定されます。 Void型のあいまいさは、null 参照を除く型Voidの参照がないため、無害です。

<h1>"invoke">アクセス モード メソッドの呼び出しのパフォーマンス</h1>invokevirtual命令が初めて実行されるときは、命令内の名前をシンボル的に解決し、メソッド呼び出しが静的に有効であることを確認することによってリンクされます。 これには、アクセス モード メソッドの呼び出しも保持されます。 この場合、コンパイラによって出力されるシンボリック型記述子で正しい構文がチェックされ、それに含まれる名前が解決されます。 したがって、シンボリック型記述子が構文的に整形式であり、型が存在する限り、アクセス モード メソッドを呼び出す invokevirtual 命令は常にリンクします。

リンク後に invokevirtual が実行されると、最初に受信 VarHandle のアクセス・モード・タイプが JVM によって検査され、シンボリック・タイプ記述子と一致することが確認されます。 型の一致が失敗した場合は、呼び出し元が呼び出しているアクセス モード メソッドが、呼び出される個々の VarHandle に存在しないことを意味します。

アクセス モード メソッドの呼び出しは、 MethodHandle#invokeの呼び出しと同様に動作します。ここで、受信側のメソッド ハンドルは、先頭の引数として VarHandle インスタンスを受け入れます。 具体的には、 {access-mode} はアクセス モードのメソッド名に対応しています。

{@code
            VarHandle vh = ..
            R r = (R) vh.{access-mode}(p1, p2, ..., pN);
            }

は次のように動作します。

{@code
            VarHandle vh = ..
            VarHandle.AccessMode am = VarHandle.AccessMode.valueFromMethodName("{access-mode}");
            MethodHandle mh = MethodHandles.varHandleExactInvoker(
                                  am,
                                  vh.accessModeType(am));

            R r = (R) mh.invoke(vh, p1, p2, ..., pN)
            }

(剰余アクセス モードのメソッドは、 Throwableのスローを宣言しません)。 これは次の内容に相当します。

{@code
            MethodHandle mh = MethodHandles.lookup().findVirtual(
                                  VarHandle.class,
                                  "{access-mode}",
                                  MethodType.methodType(R, p1, p2, ..., pN));

            R r = (R) mh.invokeExact(vh, p1, p2, ..., pN)
            }

必要なメソッド型がシンボリック型記述子であり、 MethodHandle#invokeExact が実行されます。ターゲットを呼び出す前に、ハンドルは必要に応じて参照キャストを適用し、 MethodHandle#asType asType するかのようにプリミティブ値をボックス化、ボックス解除、または拡大します ( MethodHandles#varHandleInvoker参照)。

より簡潔に言えば、このような動作は次のようになります。

{@code
            VarHandle vh = ..
            VarHandle.AccessMode am = VarHandle.AccessMode.valueFromMethodName("{access-mode}");
            MethodHandle mh = vh.toMethodHandle(am);

            R r = (R) mh.invoke(p1, p2, ..., pN)
            }

この場合、メソッド ハンドルは VarHandle インスタンスにバインドされます。

<h1>Invocation checking</h1> 一般的なプログラムでは、VarHandle アクセス モードの種類の照合は通常成功します。 しかし、一致が失敗した場合、JVM は WrongMethodTypeExceptionをスローします。

したがって、静的に型指定されたプログラムでリンケージ エラーとして表示される可能性があるアクセス モードの種類の不一致は、VarHandles を使用するプログラムで動的な WrongMethodTypeException として表示される可能性があります。

アクセス モードの型には "ライブ" Class オブジェクトが含まれているため、メソッド型の照合では型名とクラス ローダーの両方が考慮されます。 したがって、VarHandle VH が 1 つのクラス ローダー L1 で作成され、別の L2で使用されている場合でも、呼び出し元のシンボリック型記述子は、 L2で解決されているように、 L1で解決された元の呼び出し先メソッドのシンボリック型記述子と照合されるため、VarHandle アクセス モードのメソッド呼び出しは型セーフです。 L1の解決は、VHが作成され、そのアクセス モードの種類が割り当てられているときに発生しますが、L2の解決は、invokevirtual命令がリンクされたときに発生します。

型記述子チェックとは別に、VarHandles の変数にアクセスする機能は無制限です。 VarHandle が、その変数にアクセスできるクラスによって非パブリック変数に形成されている場合、結果の VarHandle は、その変数への参照を受け取る任意の呼び出し元が任意の場所で使用できます。

リフレクション メソッドが呼び出されるたびにアクセスがチェックされる Core Reflection API とは異なり、VarHandle アクセス チェックは VarHandle の作成時に実行されます。 したがって、非パブリック変数または非パブリック クラスの変数に対する VarHandles は、通常はシークレットにしておく必要があります。 信頼されていないコードからの使用が無害でない限り、信頼されていないコードに渡さないでください。

<h1>VarHandle の作成</h1> Java コードは、そのコードからアクセスできる任意のフィールドに直接アクセスする VarHandle を作成できます。 これは、 java.lang.invoke.MethodHandles.Lookup MethodHandles.Lookupと呼ばれる反射型の機能ベースの API を介して行われます。 たとえば、非静的フィールドの VarHandle は、 java.lang.invoke.MethodHandles.Lookup#findVarHandle Lookup.findVarHandleから取得できます。 java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle Lookup.unreflectVarHandle、Core Reflection API オブジェクトからの変換メソッドもあります。

保護されたフィールド メンバーへのアクセスは、アクセスするクラスまたはそのサブクラスの 1 つの受信者のみに制限され、アクセスするクラスは、保護されたメンバーの定義クラスのサブクラス (またはパッケージ兄弟) である必要があります。 VarHandle が現在のパッケージの外部にある宣言クラスの保護された非静的フィールドを参照する場合、受信側の引数はアクセスするクラスの型に絞り込まれます。

<h1>VarHandles と Core Reflection API の間の相互運用</h1>java.lang.invoke.MethodHandles.Lookup Lookup API でファクトリ メソッドを使用すると、Core Reflection API オブジェクトによって表されるフィールドは、動作に相当する VarHandle に変換できます。 たとえば、反射 java.lang.reflect.Field Field は、 java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle Lookup.unreflectVarHandleを使用して VarHandle に変換できます。 結果として得られる VarHandles は、通常、基になるフィールドへのより直接的で効率的なアクセスを提供します。

特殊なケースとして、Core Reflection API を使用してこのクラスの署名ポリモーフィック アクセス モード メソッドを表示すると、通常の非ポリモーフィック メソッドとして表示されます。 java.lang.Class#getDeclaredMethod Class.getDeclaredMethodが見た反射的な外観は、この API の特殊な状態の影響を受けません。 たとえば、 java.lang.reflect.Method#getModifiers Method.getModifiers は、同様に宣言されたメソッドに必要な修飾子ビット (この場合は native ビットや varargs ビットなど) を正確に報告します。

反映されたメソッドと同様に、これらのメソッド (反映される場合) は、 java.lang.reflect.Method#invoke java.lang.reflect.Method.invoke経由、JNI 経由、または java.lang.invoke.MethodHandles.Lookup#unreflect Lookup.unreflect経由で間接的に呼び出すことができます。 ただし、このような反射呼び出しでは、アクセス モードのメソッド呼び出しは発生しません。 このような呼び出しは、必要な引数 ( Object[]型の 1 つの引数) を渡した場合、引数を無視し、 UnsupportedOperationExceptionをスローします。

invokevirtual命令は、任意のシンボリック型記述子で VarHandle アクセス モード メソッドをネイティブに呼び出すことができるため、この反射ビューはバイトコードを介したこれらのメソッドの通常の表示と競合します。 したがって、これらのネイティブメソッドは、 Class.getDeclaredMethodによって反射的に見られる場合、プレースホルダーのみとみなされ得る。

特定のアクセス モードの種類の呼び出しメソッドを取得するには、 java.lang.invoke.MethodHandles#varHandleExactInvoker または java.lang.invoke.MethodHandles#varHandleInvokerを使用します。 java.lang.invoke.MethodHandles.Lookup#findVirtual Lookup.findVirtual API は、指定したアクセス モードの種類に対してアクセス モード メソッドを呼び出すメソッド ハンドルを返すこともできます。これは、java.lang.invoke.MethodHandles#varHandleInvokerと同等の動作です。

<h1> VarHandles と Java ジェネリックの間の相互運用</h1>ジェネリック型で宣言されているフィールドなどの変数に対して VarHandle Java取得できます。 Core Reflection API と同様に、VarHandle の変数型はソース レベルの型の消去から構築されます。 VarHandle アクセス モード メソッドが呼び出されると、その引数の型または戻り値のキャスト型がジェネリック型または型インスタンスである場合があります。 この場合、コンパイラは、 invokevirtual 命令のシンボリック型記述子を構築するときに、それらの型を消去によって置き換えます。

9 に追加されました。

Javaドキュメント。

このページの一部は、によって作成および共有され、に記載されている条件に従って使用される作業に基づく変更です。