Module java.base

Package java.lang.invoke

Class VarHandle

java.lang.Object

java.lang.invoke.VarHandle

public abstract class VarHandle
extends Object

A VarHandle is a dynamically typed reference to a variable, or to a parametrically-defined family of variables, including static fields, non-static fields, array elements, or components of an off-heap data structure. Access to such variables is supported under various access modes, including plain read/write access, volatile read/write access, and compare-and-swap.

VarHandles are immutable and have no visible state. VarHandles cannot be subclassed by the user.

A VarHandle has:

• a variable type, referred to as T, which is the type of variable(s) referenced by this VarHandle;
• a list of coordinate types, referred to as CT, where the types (primitive and reference) are represented by Class objects). A list of arguments corresponding to instances of the coordinate types uniquely locates a variable referenced by this VarHandle; and
• a shape, that combines the variable type and coordinate types, and is declared with the notation (CT : T). An empty list of coordinate types is declared as (empty).

Factory methods that produce or lookup VarHandle instances document the supported variable type, coordinate types, and shape. For example, a VarHandle referencing a non-static field will declare a shape of (R : T), where R is the receiver type and T is the field type, and where the VarHandle and an instance of the receiver type can be utilized to access the field variable. A VarHandle referencing array elements will declare a shape of (T[], int : T), where T[] is the array type and T its component type, and where the VarHandle, an instance of the array type, and an int index can be utilized to access an array element variable.

Each access mode is associated with a signature polymorphic method of the same name, where the VarHandle shape and access mode uniquely determine the canonical access mode type, which in turn determines the matching constraints on a valid symbolic type descriptor at the call site of an access mode's method invocation. As such, VarHandles are dynamically and strongly typed. Their arity, argument types, and return type of an access mode method invocation are not statically checked. If they, and associated values, do not match the arity and types of the access mode's type, an exception will be thrown. The parameter types of an access mode method type will consist of those that are the VarHandles's coordinate types (in order), followed by access mode parameter types specific to the access mode.

An access mode's method documents the form of its method signature, which is derived from the access mode parameter types. The form is declared with the notation (CT, P1 p1, P2 p2, ..., PN pn)R, where CT is the coordinate types (as documented by a VarHandle factory method), P1, P2 and PN are the first, second and the n'th access mode parameters named p1, p2 and pn respectively, and R is the return type. For example, for the generic shape of (CT : T) the compareAndSet(java.lang.Object...) access mode method documents that its method signature is of the form (CT, T expectedValue, T newValue)boolean, where the parameter types named extendedValue and newValue are the access mode parameter types. If the VarHandle accesses array elements with a shape of say (T[], int : T) then the access mode method type is (T[], int, T, T)boolean.

Access modes are grouped into the following categories:

• read access modes that get the value of a variable under specified memory ordering effects. The set of corresponding access mode methods belonging to this group consists of the methods get, getVolatile, getAcquire, getOpaque.
• write access modes that set the value of a variable under specified memory ordering effects. The set of corresponding access mode methods belonging to this group consists of the methods set, setVolatile, setRelease, setOpaque.
• atomic update access modes that, for example, atomically compare and set the value of a variable under specified memory ordering effects. The set of corresponding access mode methods belonging to this group consists of the methods compareAndSet, weakCompareAndSetPlain, weakCompareAndSet, weakCompareAndSetAcquire, weakCompareAndSetRelease, compareAndExchangeAcquire, compareAndExchange, compareAndExchangeRelease, getAndSet, getAndSetAcquire, getAndSetRelease.
• numeric atomic update access modes that, for example, atomically get and set with addition the value of a variable under specified memory ordering effects. The set of corresponding access mode methods belonging to this group consists of the methods getAndAdd, getAndAddAcquire, getAndAddRelease,
• bitwise atomic update access modes that, for example, atomically get and bitwise OR the value of a variable under specified memory ordering effects. The set of corresponding access mode methods belonging to this group consists of the methods getAndBitwiseOr, getAndBitwiseOrAcquire, getAndBitwiseOrRelease, getAndBitwiseAnd, getAndBitwiseAndAcquire, getAndBitwiseAndRelease, getAndBitwiseXor, getAndBitwiseXorAcquire, getAndBitwiseXorRelease.

Factory methods that produce or lookup VarHandle instances document the set of access modes that are supported, which may also include documenting restrictions based on the variable type and whether a variable is read-only. If an access mode is not supported then the corresponding signature-polymorphic method will on invocation throw an UnsupportedOperationException. Factory methods should document any additional undeclared exceptions that may be thrown by access mode methods. The get access mode is supported for all VarHandle instances and the corresponding method never throws UnsupportedOperationException. If a VarHandle references a read-only variable (for example a final field) then write, atomic update, numeric atomic update, and bitwise atomic update access modes are not supported and corresponding methods throw UnsupportedOperationException. Read/write access modes (if supported), with the exception of get and set, provide atomic access for reference types and all primitive types. Unless stated otherwise in the documentation of a factory method, the access modes get and set (if supported) provide atomic access for reference types and all primitives types, with the exception of long and double on 32-bit platforms.

Access modes will override any memory ordering effects specified at the declaration site of a variable. For example, a VarHandle accessing a a field using the get access mode will access the field as specified by its access mode even if that field is declared volatile. When mixed access is performed extreme care should be taken since the Java Memory Model may permit surprising results.

In addition to supporting access to variables under various access modes, a set of static methods, referred to as memory fence methods, is also provided for fine-grained control of memory ordering. The Java Language Specification permits other threads to observe operations as if they were executed in orders different than are apparent in program source code, subject to constraints arising, for example, from the use of locks, volatile fields or VarHandles. The static methods, fullFence, acquireFence, releaseFence, loadLoadFence and storeStoreFence, can also be used to impose constraints. Their specifications, as is the case for certain access modes, are phrased in terms of the lack of "reorderings" -- observable ordering effects that might otherwise occur if the fence was not present. More precise phrasing of the specification of access mode methods and memory fence methods may accompany future updates of the Java Language Specification.

Compilation of an access mode's method

A Java method call expression naming an access mode method can invoke a VarHandle from Java source code. From the viewpoint of source code, these methods can take any arguments and their polymorphic result (if expressed) can be cast to any return type. Formally this is accomplished by giving the access mode methods variable arity Object arguments and Object return types (if the return type is polymorphic), but they have an additional quality called signature polymorphism which connects this freedom of invocation directly to the JVM execution stack.

As is usual with virtual methods, source-level calls to access mode methods compile to an invokevirtual instruction. More unusually, the compiler must record the actual argument types, and may not perform method invocation conversions on the arguments. Instead, it must generate instructions to push them on the stack according to their own unconverted types. The VarHandle object itself will be pushed on the stack before the arguments. The compiler then generates an invokevirtual instruction that invokes the access mode method with a symbolic type descriptor which describes the argument and return types.

To issue a complete symbolic type descriptor, the compiler must also determine the return type (if polymorphic). This is based on a cast on the method invocation expression, if there is one, or else Object if the invocation is an expression, or else void if the invocation is a statement. The cast may be to a primitive type (but not void).

As a corner case, an uncasted null argument is given a symbolic type descriptor of java.lang.Void. The ambiguity with the type Void is harmless, since there are no references of type Void except the null reference.

Invocation of an access mode's method

The first time an invokevirtual instruction is executed it is linked by symbolically resolving the names in the instruction and verifying that the method call is statically legal. This also holds for calls to access mode methods. In this case, the symbolic type descriptor emitted by the compiler is checked for correct syntax, and names it contains are resolved. Thus, an invokevirtual instruction which invokes an access mode method will always link, as long as the symbolic type descriptor is syntactically well-formed and the types exist.

When the invokevirtual is executed after linking, the receiving VarHandle's access mode type is first checked by the JVM to ensure that it matches the symbolic type descriptor. If the type match fails, it means that the access mode method which the caller is invoking is not present on the individual VarHandle being invoked.

Invocation of an access mode's signature-polymorphic method behaves as if an invocation of MethodHandle.invoke(java.lang.Object...), where the receiving method handle is bound to a VarHandle instance and the access mode. More specifically, the following:

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

behaves as if (modulo the access mode methods do not declare throwing of Throwable):

 
 VarHandle vh = ..
 MethodHandle mh = MethodHandles.varHandleExactInvoker(
                       VarHandle.AccessMode.{access-mode},
                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));

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

or, more concisely, behaves as if:

 
 VarHandle vh = ..
 MethodHandle mh = vh.toMethodHandle(VarHandle.AccessMode.{access-mode});

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

In terms of equivalent invokevirtual bytecode behaviour an access mode method invocation is equivalent to:

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

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

where the desired method type is the symbolic type descriptor and a MethodHandle.invokeExact(java.lang.Object...) is performed, since before invocation of the target, the handle will apply reference casts as necessary and box, unbox, or widen primitive values, as if by asType (see also MethodHandles.varHandleInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType)).

Invocation checking

In typical programs, VarHandle access mode type matching will usually succeed. But if a match fails, the JVM will throw a WrongMethodTypeException.

Thus, an access mode type mismatch which might show up as a linkage error in a statically typed program can show up as a dynamic WrongMethodTypeException in a program which uses VarHandles.

Because access mode types contain "live" Class objects, method type matching takes into account both type names and class loaders. Thus, even if a VarHandle VH is created in one class loader L1 and used in another L2, VarHandle access mode method calls are type-safe, because the caller's symbolic type descriptor, as resolved in L2, is matched against the original callee method's symbolic type descriptor, as resolved in L1. The resolution in L1 happens when VH is created and its access mode types are assigned, while the resolution in L2 happens when the invokevirtual instruction is linked.

Apart from type descriptor checks, a VarHandles's capability to access it's variables is unrestricted. If a VarHandle is formed on a non-public variable by a class that has access to that variable, the resulting VarHandle can be used in any place by any caller who receives a reference to it.

Unlike with the Core Reflection API, where access is checked every time a reflective method is invoked, VarHandle access checking is performed when the VarHandle is created. Thus, VarHandles to non-public variables, or to variables in non-public classes, should generally be kept secret. They should not be passed to untrusted code unless their use from the untrusted code would be harmless.

VarHandle creation

Java code can create a VarHandle that directly accesses any field that is accessible to that code. This is done via a reflective, capability-based API called MethodHandles.Lookup. For example, a VarHandle for a non-static field can be obtained from Lookup.findVarHandle. There is also a conversion method from Core Reflection API objects, Lookup.unreflectVarHandle.

Access to protected field members is restricted to receivers only of the accessing class, or one of its subclasses, and the accessing class must in turn be a subclass (or package sibling) of the protected member's defining class. If a VarHandle refers to a protected non-static field of a declaring class outside the current package, the receiver argument will be narrowed to the type of the accessing class.

Interoperation between VarHandles and the Core Reflection API

Using factory methods in the Lookup API, any field represented by a Core Reflection API object can be converted to a behaviorally equivalent VarHandle. For example, a reflective Field can be converted to a VarHandle using Lookup.unreflectVarHandle. The resulting VarHandles generally provide more direct and efficient access to the underlying fields.

As a special case, when the Core Reflection API is used to view the signature polymorphic access mode methods in this class, they appear as ordinary non-polymorphic methods. Their reflective appearance, as viewed by Class.getDeclaredMethod, is unaffected by their special status in this API. For example, Method.getModifiers will report exactly those modifier bits required for any similarly declared method, including in this case native and varargs bits.

As with any reflected method, these methods (when reflected) may be invoked directly via java.lang.reflect.Method.invoke, via JNI, or indirectly via Lookup.unreflect. However, such reflective calls do not result in access mode method invocations. Such a call, if passed the required argument (a single one, of type Object[]), will ignore the argument and will throw an UnsupportedOperationException.

Since invokevirtual instructions can natively invoke VarHandle access mode methods under any symbolic type descriptor, this reflective view conflicts with the normal presentation of these methods via bytecodes. Thus, these native methods, when reflectively viewed by Class.getDeclaredMethod, may be regarded as placeholders only.

In order to obtain an invoker method for a particular access mode type, use MethodHandles.varHandleExactInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType) or MethodHandles.varHandleInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType). The Lookup.findVirtual API is also able to return a method handle to call an access mode method for any specified access mode type and is equivalent in behaviour to MethodHandles.varHandleInvoker(java.lang.invoke.VarHandle.AccessMode, java.lang.invoke.MethodType).

Interoperation between VarHandles and Java generics

A VarHandle can be obtained for a variable, such as a a field, which is declared with Java generic types. As with the Core Reflection API, the VarHandle's variable type will be constructed from the erasure of the source-level type. When a VarHandle access mode method is invoked, the types of its arguments or the return value cast type may be generic types or type instances. If this occurs, the compiler will replace those types by their erasures when it constructs the symbolic type descriptor for the invokevirtual instruction.

Since:

9

See Also:

MethodHandle, MethodHandles, MethodType

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	VarHandle.AccessMode	The set of access modes that specify how a variable, referenced by a VarHandle, is accessed.

Method Summary

Modifier and Type	Method	Description
MethodType	accessModeType(VarHandle.AccessMode accessMode)	Obtains the canonical access mode type for this VarHandle and a given access mode.
static void	acquireFence()	Ensures that loads before the fence will not be reordered with loads and stores after the fence.
Object	compareAndExchange(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	compareAndExchangeAcquire(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	compareAndExchangeRelease(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of setRelease(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).
boolean	compareAndSet(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).
List<Class<?>>	coordinateTypes()	Returns the coordinate types for this VarHandle.
static void	fullFence()	Ensures that loads and stores before the fence will not be reordered with loads and stores after the fence.
Object	get(Object... args)	Returns the value of a variable, with memory semantics of reading as if the variable was declared non-volatile.
Object	getAcquire(Object... args)	Returns the value of a variable, and ensures that subsequent loads and stores are not reordered before this access.
Object	getAndAdd(Object... args)	Atomically adds the value to the current value of a variable with the memory semantics of setVolatile(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	getAndAddAcquire(Object... args)	Atomically adds the value to the current value of a variable with the memory semantics of set(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	getAndAddRelease(Object... args)	Atomically adds the value to the current value of a variable with the memory semantics of setRelease(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).
Object	getAndBitwiseAnd(Object... args)	Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	getAndBitwiseAndAcquire(Object... args)	Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	getAndBitwiseAndRelease(Object... args)	Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).
Object	getAndBitwiseOr(Object... args)	Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	getAndBitwiseOrAcquire(Object... args)	Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	getAndBitwiseOrRelease(Object... args)	Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).
Object	getAndBitwiseXor(Object... args)	Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	getAndBitwiseXorAcquire(Object... args)	Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	getAndBitwiseXorRelease(Object... args)	Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).
Object	getAndSet(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).
Object	getAndSetAcquire(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).
Object	getAndSetRelease(Object... args)	Atomically sets the value of a variable to the newValue with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).
Object	getOpaque(Object... args)	Returns the value of a variable, accessed in program order, but with no assurance of memory ordering effects with respect to other threads.
Object	getVolatile(Object... args)	Returns the value of a variable, with memory semantics of reading as if the variable was declared volatile.
boolean	isAccessModeSupported(VarHandle.AccessMode accessMode)	Returns true if the given access mode is supported, otherwise false.
static void	loadLoadFence()	Ensures that loads before the fence will not be reordered with loads after the fence.
static void	releaseFence()	Ensures that loads and stores before the fence will not be reordered with stores after the fence.
void	set(Object... args)	Sets the value of a variable to the newValue, with memory semantics of setting as if the variable was declared non-volatile and non-final.
void	setOpaque(Object... args)	Sets the value of a variable to the newValue, in program order, but with no assurance of memory ordering effects with respect to other threads.
void	setRelease(Object... args)	Sets the value of a variable to the newValue, and ensures that prior loads and stores are not reordered after this access.
void	setVolatile(Object... args)	Sets the value of a variable to the newValue, with memory semantics of setting as if the variable was declared volatile.
static void	storeStoreFence()	Ensures that stores before the fence will not be reordered with stores after the fence.
MethodHandle	toMethodHandle(VarHandle.AccessMode accessMode)	Obtains a method handle bound to this VarHandle and the given access mode.
Class<?>	varType()	Returns the variable type of variables referenced by this VarHandle.
boolean	weakCompareAndSet(Object... args)	Possibly atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).
boolean	weakCompareAndSetAcquire(Object... args)	Possibly atomically sets the value of a variable to the newValue with the semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getAcquire(java.lang.Object...).
boolean	weakCompareAndSetPlain(Object... args)	Possibly atomically sets the value of a variable to the newValue with the semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).
boolean	weakCompareAndSetRelease(Object... args)	Possibly atomically sets the value of a variable to the newValue with the semantics of setRelease(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).

Methods inherited from class java.lang.Object

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

Method Detail

get

public final Object get(Object... args)

Returns the value of a variable, with memory semantics of reading as if the variable was declared non-volatile. Commonly referred to as plain read access.

The method signature is of the form (CT)T.

The symbolic type descriptor at the call site of get must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET) on this VarHandle.

This access mode is supported by all VarHandle instances and never throws UnsupportedOperationException.

Parameters:

args - the signature-polymorphic parameter list of the form (CT) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the value of the variable , statically represented using Object.

Throws:

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

set

public final void set(Object... args)

Sets the value of a variable to the newValue, with memory semantics of setting as if the variable was declared non-volatile and non-final. Commonly referred to as plain write access.

The method signature is of the form (CT, T newValue)void

The symbolic type descriptor at the call site of set must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.SET) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

getVolatile

public final Object getVolatile(Object... args)

Returns the value of a variable, with memory semantics of reading as if the variable was declared volatile.

The method signature is of the form (CT)T.

The symbolic type descriptor at the call site of getVolatile must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_VOLATILE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

setVolatile

public final void setVolatile(Object... args)

Sets the value of a variable to the newValue, with memory semantics of setting as if the variable was declared volatile.

The method signature is of the form (CT, T newValue)void.

The symbolic type descriptor at the call site of setVolatile must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.SET_VOLATILE) on this VarHandle.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with memory_order_seq_cst.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

getOpaque

public final Object getOpaque(Object... args)

Returns the value of a variable, accessed in program order, but with no assurance of memory ordering effects with respect to other threads.

The method signature is of the form (CT)T.

The symbolic type descriptor at the call site of getOpaque must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_OPAQUE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

setOpaque

public final void setOpaque(Object... args)

Sets the value of a variable to the newValue, in program order, but with no assurance of memory ordering effects with respect to other threads.

The method signature is of the form (CT, T newValue)void.

The symbolic type descriptor at the call site of setOpaque must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.SET_OPAQUE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

getAcquire

public final Object getAcquire(Object... args)

Returns the value of a variable, and ensures that subsequent loads and stores are not reordered before this access.

The method signature is of the form (CT)T.

The symbolic type descriptor at the call site of getAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_ACQUIRE) on this VarHandle.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with memory_order_acquire ordering.

Parameters:

args - the signature-polymorphic parameter list of the form (CT) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

setRelease

public final void setRelease(Object... args)

Sets the value of a variable to the newValue, and ensures that prior loads and stores are not reordered after this access.

The method signature is of the form (CT, T newValue)void.

The symbolic type descriptor at the call site of setRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.SET_RELEASE) on this VarHandle.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with memory_order_release ordering.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

compareAndSet

public final boolean compareAndSet(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).

The method signature is of the form (CT, T expectedValue, T newValue)boolean.

The symbolic type descriptor at the call site of compareAndSet must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.COMPARE_AND_SET) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

true if successful, otherwise false if the witness value was not the same as the expectedValue.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

compareAndExchange

public final Object compareAndExchange(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).

The method signature is of the form (CT, T expectedValue, T newValue)T.

The symbolic type descriptor at the call site of compareAndExchange must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the witness value, which will be the same as the expectedValue if successful , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

compareAndExchangeAcquire

public final Object compareAndExchangeAcquire(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getAcquire(java.lang.Object...).

The method signature is of the form (CT, T expectedValue, T newValue)T.

The symbolic type descriptor at the call site of compareAndExchangeAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the witness value, which will be the same as the expectedValue if successful , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), getAcquire(Object...)

compareAndExchangeRelease

public final Object compareAndExchangeRelease(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of setRelease(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).

The method signature is of the form (CT, T expectedValue, T newValue)T.

The symbolic type descriptor at the call site of compareAndExchangeRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.COMPARE_AND_EXCHANGE_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the witness value, which will be the same as the expectedValue if successful , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setRelease(Object...), get(Object...)

weakCompareAndSetPlain

public final boolean weakCompareAndSetPlain(Object... args)

Possibly atomically sets the value of a variable to the newValue with the semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).

This operation may fail spuriously (typically, due to memory contention) even if the witness value does match the expected value.

The method signature is of the form (CT, T expectedValue, T newValue)boolean.

The symbolic type descriptor at the call site of weakCompareAndSetPlain must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_PLAIN) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

true if successful, otherwise false if the witness value was not the same as the expectedValue or if this operation spuriously failed.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), get(Object...)

weakCompareAndSet

public final boolean weakCompareAndSet(Object... args)

Possibly atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getVolatile(java.lang.Object...).

This operation may fail spuriously (typically, due to memory contention) even if the witness value does match the expected value.

The method signature is of the form (CT, T expectedValue, T newValue)boolean.

The symbolic type descriptor at the call site of weakCompareAndSet must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

true if successful, otherwise false if the witness value was not the same as the expectedValue or if this operation spuriously failed.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

weakCompareAndSetAcquire

public final boolean weakCompareAndSetAcquire(Object... args)

Possibly atomically sets the value of a variable to the newValue with the semantics of set(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of getAcquire(java.lang.Object...).

This operation may fail spuriously (typically, due to memory contention) even if the witness value does match the expected value.

The method signature is of the form (CT, T expectedValue, T newValue)boolean.

The symbolic type descriptor at the call site of weakCompareAndSetAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

true if successful, otherwise false if the witness value was not the same as the expectedValue or if this operation spuriously failed.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), getAcquire(Object...)

weakCompareAndSetRelease

public final boolean weakCompareAndSetRelease(Object... args)

Possibly atomically sets the value of a variable to the newValue with the semantics of setRelease(java.lang.Object...) if the variable's current value, referred to as the witness value, == the expectedValue, as accessed with the memory semantics of get(java.lang.Object...).

This operation may fail spuriously (typically, due to memory contention) even if the witness value does match the expected value.

The method signature is of the form (CT, T expectedValue, T newValue)boolean.

The symbolic type descriptor at the call site of weakCompareAndSetRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.WEAK_COMPARE_AND_SET_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T expectedValue, T newValue) , statically represented using varargs.

Returns:

true if successful, otherwise false if the witness value was not the same as the expectedValue or if this operation spuriously failed.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setRelease(Object...), get(Object...)

getAndSet

public final Object getAndSet(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).

The method signature is of the form (CT, T newValue)T.

The symbolic type descriptor at the call site of getAndSet must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_SET) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndSetAcquire

public final Object getAndSetAcquire(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).

The method signature is of the form (CT, T newValue)T.

The symbolic type descriptor at the call site of getAndSetAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_SET_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndSetRelease

public final Object getAndSetRelease(Object... args)

Atomically sets the value of a variable to the newValue with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).

The method signature is of the form (CT, T newValue)T.

The symbolic type descriptor at the call site of getAndSetRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_SET_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T newValue) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndAdd

public final Object getAndAdd(Object... args)

Atomically adds the value to the current value of a variable with the memory semantics of setVolatile(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).

The method signature is of the form (CT, T value)T.

The symbolic type descriptor at the call site of getAndAdd must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_ADD) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T value) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndAddAcquire

public final Object getAndAddAcquire(Object... args)

Atomically adds the value to the current value of a variable with the memory semantics of set(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).

The method signature is of the form (CT, T value)T.

The symbolic type descriptor at the call site of getAndAddAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_ADD_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T value) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndAddRelease

public final Object getAndAddRelease(Object... args)

Atomically adds the value to the current value of a variable with the memory semantics of setRelease(java.lang.Object...), and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).

The method signature is of the form (CT, T value)T.

The symbolic type descriptor at the call site of getAndAddRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_ADD_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T value) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndBitwiseOr

public final Object getAndBitwiseOr(Object... args)

Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical OR is performed instead of a bitwise OR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseOr must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndBitwiseOrAcquire

public final Object getAndBitwiseOrAcquire(Object... args)

Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical OR is performed instead of a bitwise OR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseOrAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), getAcquire(Object...)

getAndBitwiseOrRelease

public final Object getAndBitwiseOrRelease(Object... args)

Atomically sets the value of a variable to the result of bitwise OR between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical OR is performed instead of a bitwise OR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseOrRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_OR_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setRelease(Object...), get(Object...)

getAndBitwiseAnd

public final Object getAndBitwiseAnd(Object... args)

Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical AND is performed instead of a bitwise AND.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseAnd must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndBitwiseAndAcquire

public final Object getAndBitwiseAndAcquire(Object... args)

Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical AND is performed instead of a bitwise AND.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseAndAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), getAcquire(Object...)

getAndBitwiseAndRelease

public final Object getAndBitwiseAndRelease(Object... args)

Atomically sets the value of a variable to the result of bitwise AND between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical AND is performed instead of a bitwise AND.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseAndRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_AND_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setRelease(Object...), get(Object...)

getAndBitwiseXor

public final Object getAndBitwiseXor(Object... args)

Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of setVolatile(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getVolatile(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical XOR is performed instead of a bitwise XOR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseXor must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setVolatile(Object...), getVolatile(Object...)

getAndBitwiseXorAcquire

public final Object getAndBitwiseXorAcquire(Object... args)

Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of set(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of getAcquire(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical XOR is performed instead of a bitwise XOR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseXorAcquire must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR_ACQUIRE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

set(Object...), getAcquire(Object...)

getAndBitwiseXorRelease

public final Object getAndBitwiseXorRelease(Object... args)

Atomically sets the value of a variable to the result of bitwise XOR between the variable's current value and the mask with the memory semantics of setRelease(java.lang.Object...) and returns the variable's previous value, as accessed with the memory semantics of get(java.lang.Object...).

If the variable type is the non-integral boolean type then a logical XOR is performed instead of a bitwise XOR.

The method signature is of the form (CT, T mask)T.

The symbolic type descriptor at the call site of getAndBitwiseXorRelease must match the access mode type that is the result of calling accessModeType(VarHandle.AccessMode.GET_AND_BITWISE_XOR_RELEASE) on this VarHandle.

Parameters:

args - the signature-polymorphic parameter list of the form (CT, T mask) , statically represented using varargs.

Returns:

the signature-polymorphic result that is the previous value of the variable , statically represented using Object.

Throws:

UnsupportedOperationException - if the access mode is unsupported for this VarHandle.

WrongMethodTypeException - if the access mode type is not compatible with the caller's symbolic type descriptor.

ClassCastException - if the access mode type is compatible with the caller's symbolic type descriptor, but a reference cast fails.

See Also:

setRelease(Object...), get(Object...)

varType

public final Class<?> varType()

Returns the variable type of variables referenced by this VarHandle.

Returns:

the variable type of variables referenced by this VarHandle

coordinateTypes

public final List<Class<?>> coordinateTypes()

Returns the coordinate types for this VarHandle.

Returns:

the coordinate types for this VarHandle. The returned list is unmodifiable

accessModeType

public final MethodType accessModeType(VarHandle.AccessMode accessMode)

Obtains the canonical access mode type for this VarHandle and a given access mode.

The access mode type's parameter types will consist of a prefix that is the coordinate types of this VarHandle followed by further types as defined by the access mode's method. The access mode type's return type is defined by the return type of the access mode's method.

Parameters:

accessMode - the access mode, corresponding to the signature-polymorphic method of the same name

Returns:

the access mode type for the given access mode

isAccessModeSupported

public final boolean isAccessModeSupported(VarHandle.AccessMode accessMode)

Returns true if the given access mode is supported, otherwise false.

The return of a false value for a given access mode indicates that an UnsupportedOperationException is thrown on invocation of the corresponding access mode's signature-polymorphic method.

Parameters:

accessMode - the access mode, corresponding to the signature-polymorphic method of the same name

Returns:

true if the given access mode is supported, otherwise false.

toMethodHandle

public final MethodHandle toMethodHandle(VarHandle.AccessMode accessMode)

Obtains a method handle bound to this VarHandle and the given access mode.

API Note:

This method, for a VarHandle vh and access mode {access-mode}, returns a method handle that is equivalent to method handle bhm in the following code (though it may be more efficient):

 MethodHandle mh = MethodHandles.varHandleExactInvoker(
                       vh.accessModeType(VarHandle.AccessMode.{access-mode}));

 MethodHandle bmh = mh.bindTo(vh);
 

Parameters:

accessMode - the access mode, corresponding to the signature-polymorphic method of the same name

Returns:

a method handle bound to this VarHandle and the given access mode

fullFence

public static void fullFence()

Ensures that loads and stores before the fence will not be reordered with loads and stores after the fence.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with atomic_thread_fence(memory_order_seq_cst)

acquireFence

public static void acquireFence()

Ensures that loads before the fence will not be reordered with loads and stores after the fence.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with atomic_thread_fence(memory_order_acquire)

releaseFence

public static void releaseFence()

Ensures that loads and stores before the fence will not be reordered with stores after the fence.

API Note:

Ignoring the many semantic differences from C and C++, this method has memory ordering effects compatible with atomic_thread_fence(memory_order_release)

loadLoadFence

public static void loadLoadFence()

Ensures that loads before the fence will not be reordered with loads after the fence.

storeStoreFence

public static void storeStoreFence()

Ensures that stores before the fence will not be reordered with stores after the fence.