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

Object

VarHandle

屬性

RegisterAttribute

備註

VarHandle 是動態強型別的變數參考，或參數定義的變數系列，包括靜態字段、非靜態字段、數組元素或非堆積數據結構的元件。 在各種 <em>存取模式</em>下支援這類變數的存取，包括一般讀取/寫入存取、揮發性讀取/寫入存取，以及 compare-and-set。

VarHandles 是不可變的，而且沒有可見的狀態。 VarHandles 無法由使用者子類別化。

VarHandle 具有：<ul<>li>a #varType variable type T、此 VarHandle 所參考之每個變數的類型;以及 <li 清單CT1, CT2, ..., CTn#coordinateTypes coordinate types，以及 em>> 座標運算式</em> 的類型<，可聯合找出此 VarHandle 所參考的變數。 </ul> 變數和座標類型可以是基本類型或參考，而且是由 Class 物件表示。 座標類型清單可能是空的。

產生 或 java.lang.invoke.MethodHandles.Lookup lookup VarHandle 實例的 Factory 方法會記載支援的變數類型和座標類型清單。

每個存取模式都與一個 <em>存取模式方法</em> 相關聯，這是針對存取模式命名的簽章多型方法。 在 VarHandle 實體上叫用存取模式方法時，叫用的初始自變數是座標表示式，指出要存取變數的物件。 叫用的尾端自變數代表存取模式的重要性值。 例如，各種 compare-and-set 或 compare-and-exchange 存取模式需要變數預期值和新值的兩個尾端自變數。

存取模式方法調用的自變數和類型不會以靜態方式檢查。 相反地，每個存取模式方法都會 #accessModeType(AccessMode) access mode type指定 ，以 實例表示 MethodType，做為動態檢查自變數的方法簽章。 存取模式類型會根據 VarHandle 實例的座標類型，以及存取模式值的值來提供正式參數類型。 存取模式類型也會提供傳回型別，通常就 VarHandle 實例的變數類型而言。 在 VarHandle 實體上叫用存取模式方法時，呼叫月臺的符號型別描述項、叫用的自變數運行時間類型，以及傳回值的運行時間類型，必須符合存取模式類型中指定的類型。 如果比對失敗，將會擲回運行時間例外狀況。

例如，存取模式方法 #compareAndSet 會指定，如果接收者是具有座標類型和變數類型的 CT1, ..., CTn VarHandle 實體，則其存取模式類型 T為 (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>> read （） 和 write （setget） 存取權保證只有參考和基本值最多 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 update access 模式，例如，在指定的記憶體排序效果下，以不可部分完成方式比較和設定變數的值。 屬於此群組的對應存取模式方法集合包含方法、、、、#weakCompareAndSetAcquire weakCompareAndSetAcquire、 #getAndSetRelease getAndSetRelease#getAndSetAcquire getAndSetAcquire#getAndSet getAndSet#compareAndExchangeRelease compareAndExchangeRelease#compareAndExchange compareAndExchange#weakCompareAndSetRelease weakCompareAndSetRelease#compareAndExchangeAcquire compareAndExchangeAcquire#weakCompareAndSet weakCompareAndSet#weakCompareAndSetPlain weakCompareAndSetPlain#compareAndSet compareAndSet <li>numeric atomic update access 模式，例如，以不可部分完成的方式取得和設定，並在指定的記憶體排序效果下新增變數的值。 屬於這個群組的對應存取模式方法集合是由方法 #getAndAdd getAndAdd、 #getAndAddAcquire getAndAddAcquire、 #getAndAddRelease getAndAddRelease、 <li>位不可部分完成的更新存取模式所組成，例如，在指定的記憶體排序效果下，以不可部分完成方式取得和位或變數的值。 屬於此群組的對應存取模式方法集合包含方法 、、、、#getAndBitwiseAndAcquire getAndBitwiseAndAcquire、#getAndBitwiseOrAcquire getAndBitwiseOrAcquire#getAndBitwiseOrRelease getAndBitwiseOrRelease#getAndBitwiseXorRelease getAndBitwiseXorRelease#getAndBitwiseXorAcquire getAndBitwiseXorAcquire#getAndBitwiseOr getAndBitwiseOr#getAndBitwiseXor getAndBitwiseXor#getAndBitwiseAnd getAndBitwiseAnd#getAndBitwiseAndRelease getAndBitwiseAndRelease </ul>

產生 或 java.lang.invoke.MethodHandles.Lookup lookup VarHandle 實例的 Factory 方法會記錄支援的存取模式集合，這也可能包含根據變數類型以及變數是否為唯讀的檔限制。 如果不支援存取模式，則對應的存取模式方法會在呼叫時擲回 UnsupportedOperationException。 Factory 方法應該記錄存取模式方法可能擲回的任何其他未宣告例外狀況。 #get get所有 VarHandle 實體都支援存取模式，而且對應的方法永遠不會擲回 UnsupportedOperationException。 如果 VarHandle 參考唯讀變數（例如 final 欄位），則不支援寫入、不可部分完成更新、數值不可部分完成更新和位不可部分完成更新存取模式，且對應的方法會擲回 UnsupportedOperationException。 讀取/寫入存取模式（如果支援），除了 get 和 set之外，提供參考型別和所有基本型別的不可部分完成存取權。 除非在 Factory 方法的檔案中另有說明，否則存取模式get和 （如果支援）會提供參考型別和所有基本類型不可部分完成的存取，但 32 位平臺上除外 doublelongset 。

存取模式會覆寫變數宣告月臺所指定的任何記憶體排序效果。 例如，使用get存取模式存取欄位的 VarHandle，即使宣告volatile了該欄位，也會透過其存取模式</em> 指定<>來存取字段。 當執行混合式存取時，應該非常小心，因為 Java 記憶體模型可能會允許令人驚訝的結果。

除了支持在各種存取模式下存取變數之外，還會提供一組稱為記憶體柵欄方法的靜態方法，以精細控制記憶體順序。

Java 語言規格允許其他線程觀察作業，就像是以程式原始碼中明顯不同的順序執行作業，但受限於限制式，例如，使用鎖定、 volatile 字段或 VarHandles。 靜態方法、#fullFence fullFence、#acquireFence acquireFence、 #loadLoadFence loadLoadFence#releaseFence releaseFence和 #storeStoreFence storeStoreFence也可以用來強加條件約束。 其規格與某些存取模式的情況一樣，在缺乏「重新排列」方面是片語的--如果圍欄不存在，則可能會發生可觀察的排序效果。 更精確的存取模式方法和記憶體圍欄方法規格的片語，可能會伴隨Java語言規格的未來更新。

<h1>編譯存取模式方法<的調用/h1> Java 方法呼叫表示式，命名存取模式方法可以從 Java 原始程式碼叫用 VarHandle。 從原始程式碼的觀點來看，這些方法可以接受任何自變數及其多型結果（如果表示）可以轉換成任何傳回型別。 正式完成這項作業的方式是授與存取模式方法變數arity Object 自變數和Object傳回型別（如果傳回型別為多型），但它們有稱為em>簽章多型</em>的額外品質<，可將這種調用自由直接連接到 JVM 執行堆疊。

與虛擬方法一樣，存取模式方法的來源層級呼叫會編譯成 invokevirtual 指令。 更不尋常的是，編譯程式必須記錄實際的自變數類型，而且可能不會在自變數上執行方法調用轉換。 相反地，它必須產生指示，根據自己的未轉換類型在堆疊上推送它們。 VarHandle 物件本身會在自變數之前推送到堆疊上。 然後，編譯程式會產生 invokevirtual 指令，以符號型別描述元叫用存取模式方法，描述自變數和傳回型別。

若要發出完整的符號類型描述元，編譯程式也必須判斷傳回類型（如果多型）。 這是根據方法調用表達式的轉換，如果有的話，或者 Object ，如果調用是表達式，則為 ，否則 void 如果叫用是語句， 則為 。 轉換可以是基本類型（但不是 void）。

在邊角案例中，未轉換 null 的自變數會得到 的 java.lang.Void符號型別描述元。 型別的模棱兩可 Void 是無害的，因為除了 Null 參考之外，沒有類型的 Void 參考。

<h1>“invoke”>執行存取模式方法<的調用/h1> 第一次 invokevirtual 執行指令時，會透過符號方式解析指令中的名稱，並確認方法呼叫是靜態合法的連結。 這也會保留對存取模式方法的呼叫。 在此情況下，會檢查編譯程式發出的符號類型描述元，以取得正確的語法，並解析它所包含的名稱。 因此， invokevirtual 只要符號型別描述元的格式正確且類型存在，叫用存取模式方法的指令一律會連結。

invokevirtual在鏈接之後執行 時，JVM 會先檢查接收 VarHandle 的存取模式類型，以確保它符合符號類型描述元。 如果類型比對失敗，表示呼叫端叫用的存取模式方法不存在於所叫用的個別 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 會執行 ，因為在叫用目標之前，句柄會視需要套用參考轉換，box、unbox 或擴展基本值，就像是 by 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>調用檢查</h1> 在一般程式中，VarHandle 存取模式類型比對通常會成功。 但是，如果比對失敗，JVM 會擲回 WrongMethodTypeException。

因此，存取模式類型不符，在靜態型別程式中可能會顯示為連結錯誤，可能會在使用 VarHandles 的程式中顯示為動態 WrongMethodTypeException 。

由於存取模式類型包含「即時」 Class 物件，因此方法類型比對會同時考慮類型名稱和類別載入器。 因此，即使在某個類別載入器L1中建立 VarHandle VH 並用於另一L2個 ，VarHandle 存取模式方法呼叫是類型安全，因為呼叫端的符號類型描述元，如 中所L2解析，會與原始被呼叫者方法的符號類型描述元進行比對，如 中所L1解析。 中解析 L1 會在建立時 VH 發生，且其存取模式類型已指派，而中的 L2 解析會在指示連結時 invokevirtual 發生。

除了類型描述元檢查之外，VarHandles 存取變數的功能不受限制。 如果 VarHandle 是由可存取該變數的類別在非公用變數上形成，則任何接收該變數參考的呼叫端都可以在任何位置使用產生的 VarHandle。

不同於核心反映 API，每次叫用反映方法時都會檢查存取權，建立 VarHandle 時會執行 VarHandle 存取檢查。 因此，VarHandles 對非公用變數，或非公用類別中的變數，通常應該保密。 除非使用不受信任的程式代碼，否則不應將其傳遞至不受信任的程序代碼。

<h1>VarHandle 建立</h1> Java 程式代碼可以建立 VarHandle，直接存取該程式代碼可存取的任何字段。 這是透過稱為 java.lang.invoke.MethodHandles.Lookup MethodHandles.Lookup的反射式功能型 API 來完成。 例如，可以從 取得 java.lang.invoke.MethodHandles.Lookup#findVarHandle Lookup.findVarHandle非靜態字段的 VarHandle。 核心反映 API 物件也有轉換方法。 java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle Lookup.unreflectVarHandle

受保護欄位成員的存取僅限於存取類別或其中一個子類別的接收者，而存取類別也必須是受保護成員定義類別的子類別（或封裝同層級）。 如果 VarHandle 參考目前封裝外部宣告類別的受保護非靜態欄位，接收者自變數將會縮小為存取類別的類型。

<h1>在 VarHandles 與 Core Reflection API</h1> 之間互通使用 API 中的 java.lang.invoke.MethodHandles.Lookup Lookup Factory 方法，核心反映 API 物件所代表的任何欄位都可以轉換成行為相等的 VarHandle。 例如，反光 java.lang.reflect.Field Field 鏡可以使用 轉換成 VarHandle java.lang.invoke.MethodHandles.Lookup#unreflectVarHandle Lookup.unreflectVarHandle。 產生的 VarHandles 通常會提供對基礎欄位的更直接且有效率的存取。

作為特殊案例，當核心反映 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[]變數），則這類呼叫會忽略 自變數，並將擲回 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 泛型類型宣告的字段。 如同核心反映 API，VarHandle 的變數類型將會從來源層級類型的清除建構。 叫用 VarHandle 存取模式方法時，其自變數的類型或傳回值轉換類型可能是泛型類型或類型實例。 如果發生這種情況，編譯程式會在建構指令的符號類型描述元時，將其清除取代這些 invokevirtual 類型。

已在 9 中新增。

的 java.lang.invoke.VarHandleJava 檔。

此頁面的部分是根據 Android 開放原始碼專案所建立和共用的工作進行修改，並根據 Creative Commons 2.5 屬性授權中所述的詞彙使用。

建構函式

屬性

方法

明確介面實作

擴充方法

適用於